<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
    <title>10.1 REST 3.2.11</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
    <link rel="stylesheet" href="../css/pdf.css" type="text/css" media="print" title="PDF" charset="utf-8"/>
    <script type="text/javascript">
function addJsClass() {
    var classes = document.body.className.split(" ");
    classes.push("js");
    document.body.className = classes.join(" ");
}
    </script>
</head>

<body class="body" onload="addJsClass();">
<div id="navigation">
    <div class="navTitle">
        
        The Grails Framework
    </div>
    <div class="navLinks">
        <ul>
            <li>
                <div id="nav-summary" onmouseover="toggleNavSummary(false)" onmouseout="toggleNavSummary(true)">
                    <a href="../../guide/index.html" class="button">Table of contents</a>

                    <div id="nav-summary-childs" style="display:none;">
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/introduction.html"><strong>1</strong><span>Introduction</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/gettingStarted.html"><strong>2</strong><span>Getting Started</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/upgrading.html"><strong>3</strong><span>Upgrading</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/conf.html"><strong>4</strong><span>Configuration</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/commandLine.html"><strong>5</strong><span>The Command Line</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/profiles.html"><strong>6</strong><span>Application Profiles</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/GORM.html"><strong>7</strong><span>Object Relational Mapping (GORM)</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/theWebLayer.html"><strong>8</strong><span>The Web Layer</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/traits.html"><strong>9</strong><span>Traits</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/webServices.html"><strong>10</strong><span>Web Services</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/async.html"><strong>11</strong><span>Asynchronous Programming</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/validation.html"><strong>12</strong><span>Validation</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/services.html"><strong>13</strong><span>The Service Layer</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/staticTypeCheckingAndCompilation.html"><strong>14</strong><span>Static Type Checking And Compilation</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/testing.html"><strong>15</strong><span>Testing</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/i18n.html"><strong>16</strong><span>Internationalization</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/security.html"><strong>17</strong><span>Security</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/plugins.html"><strong>18</strong><span>Plugins</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/spring.html"><strong>19</strong><span>Grails and Spring</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/hibernate.html"><strong>20</strong><span>Grails and Hibernate</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/scaffolding.html"><strong>21</strong><span>Scaffolding</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/deployment.html"><strong>22</strong><span>Deployment</span></a>
                        </div>
                        
                        <div class="toc-item" style="margin-left:0"><a href="../../guide/contributing.html"><strong>23</strong><span>Contributing to Grails</span></a>
                        </div>
                        
                    </div>
                </div>
            </li>
            <li class="separator selected">
                <a id="ref-button" onclick="localToggle(); return false;" href="#">Quick Reference</a>
            </li>
        </ul>
    </div>


</div>

<table id="colset" border="0" cellpadding="0" cellspacing="0">
    <tr>
        <td id="col1">
            <div id="main" class="corner-all">

                
                    <div class="toc-item prev-left"><a href="../../guide/traits.html">&lt;&lt; <strong>9</strong><span>Traits</span></a></div>
                

                <span id='toggle-col1' class="toggle">(<a href="#" onclick="localToggle(); return false;">Quick Reference</a>)</span>

                
                    <div class="toc-item next-right"><a href="../../guide/async.html"><strong>11</strong><span>Asynchronous Programming</span> >></a></div>
                


                <div class="project">
                    <h1>10.1 REST</h1>

                    <p><strong>Version:</strong> 3.2.11</p>
                </div>

                
                <div id="table-of-content">
                    <h2>Table of Contents</h2>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#domainResources"><strong>10.1</strong><span>Domain classes as REST resources</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#urlMappings"><strong>10.2</strong><span>Mapping to REST resources</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#linkingToResources"><strong>10.3</strong><span>Linking to REST resources from GSP pages</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#versioningResources"><strong>10.4</strong><span>Versioning REST resources</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#restfulControllers"><strong>10.5</strong><span>Implementing REST controllers</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#extendingRestfulController"><strong>10.5.1</strong><span>Extending the RestfulController super class</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#restControllersStepByStep"><strong>10.5.2</strong><span>Implementing REST Controllers Step by Step</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#generatingRestControllers"><strong>10.5.3</strong><span>Generating a REST controller using scaffolding</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#restProfile"><strong>10.6</strong><span>The REST Profile</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#angularJsProfile"><strong>10.7</strong><span>The AngularJS Profile</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#angularProfile"><strong>10.8</strong><span>The Angular Profile</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#jsonViews"><strong>10.9</strong><span>JSON Views</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#jsonViewsSetup"><strong>10.9.1</strong><span>Getting Started</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#jsonViewsCreating"><strong>10.9.2</strong><span>Creating JSON Views</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#jsonViewsAndTemplates"><strong>10.9.3</strong><span>JSON View Templates</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#jsonViewsAndDomainClasses"><strong>10.9.4</strong><span>Rendering Domain Classes with JSON Views</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#jsonViewsTemplatesAndConventions"><strong>10.9.5</strong><span>JSON Views by Convention</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#renderers"><strong>10.10</strong><span>Customizing Response Rendering</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#defaultRenderers"><strong>10.10.1</strong><span>Customizing the Default Renderers</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#customRenderers"><strong>10.10.2</strong><span>Implementing a Custom Renderer</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#gspRenderers"><strong>10.10.3</strong><span>Using GSP to Customize Rendering</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#hypermedia"><strong>10.11</strong><span>Hypermedia as the Engine of Application State</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#hal"><strong>10.11.1</strong><span>HAL Support</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#atom"><strong>10.11.2</strong><span>Atom Support</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#vndError"><strong>10.11.3</strong><span>Vnd.Error Support</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#binding"><strong>10.12</strong><span>Customizing Binding of Resources</span></a>
                    </div>
                    
                </div>
                

                
<a name="8.1 REST"><!-- Legacy link --></a>
<h2 id="REST">10.1 REST</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>REST is not really a technology in itself, but more an architectural pattern. REST is very simple and just involves using plain XML or JSON as a communication medium, combined with URL patterns that are "representational" of the underlying system, and HTTP methods such as GET, PUT, POST and DELETE.</p>
</div>
<div class="paragraph">
<p>Each HTTP method maps to an action type. For example GET for retrieving data, POST for creating data, PUT for updating and so on.</p>
</div>
<div class="paragraph">
<p>Grails includes flexible features that make it easy to create RESTful APIs. Creating a RESTful resource can be as simple as one line of code, as demonstrated in the next section.</p>
</div>


<h2 id="domainResources">10.1.1 Domain classes as REST resources</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/domainResources.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>The easiest way to create a RESTful API in Grails is to expose a domain class as a REST resource. This can be done by adding the <code>grails.rest.Resource</code> transformation to any domain class:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.*</span>

<span class="annotation">@Resource</span>(uri=<span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>)
<span class="type">class</span> <span class="class">Book</span> {

    <span class="predefined-type">String</span> title

    <span class="directive">static</span> constraints = {
        title <span class="key">blank</span>:<span class="predefined-constant">false</span>
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Simply by adding the <code>Resource</code> transformation and specifying a URI, your domain class will automatically be available as a REST resource in either XML or JSON formats. The transformation will automatically register the necessary <a href="theWebLayer.html#restfulMappings">RESTful URL mapping</a> and create a controller called <code>BookController</code>.</p>
</div>
<div class="paragraph">
<p>You can try it out by adding some test data to <code>BootStrap.groovy</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> init = { servletContext -&gt;
    <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">The Stand</span><span class="delimiter">&quot;</span></span>).save()
    <span class="keyword">new</span> <span class="predefined-type">Book</span>(<span class="key">title</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">The Shining</span><span class="delimiter">&quot;</span></span>).save()
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>And then hitting the URL <a href="http://localhost:8080/books/1" class="bare">http://localhost:8080/books/1</a>, which will render the response like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="preprocessor">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="tag">&lt;book</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
    <span class="tag">&lt;title&gt;</span>The Stand<span class="tag">&lt;/title&gt;</span>
<span class="tag">&lt;/book&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>If you change the URL to <a href="http://localhost:8080/books/1.json" class="bare">http://localhost:8080/books/1.json</a> you will get a JSON response such as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="json">{<span class="key"><span class="delimiter">&quot;</span><span class="content">id</span><span class="delimiter">&quot;</span></span>:<span class="integer">1</span>,<span class="key"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">The Stand</span><span class="delimiter">&quot;</span></span>}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you wish to change the default to return JSON instead of XML, you can do this by setting the <code>formats</code> attribute of the <code>Resource</code> transformation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.*</span>

<span class="annotation">@Resource</span>(uri=<span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>, formats=[<span class="string"><span class="delimiter">'</span><span class="content">json</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">xml</span><span class="delimiter">'</span></span>])
<span class="type">class</span> <span class="class">Book</span> {
    ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the above example JSON will be prioritized. The list that is passed should contain the names of the formats that the resource should expose. The names of formats are defined in the <code>grails.mime.types</code> setting of <code>application.groovy</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">grails.mime.types = [
    ...
    json:          [<span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">text/json</span><span class="delimiter">'</span></span>],
    ...
    xml:           [<span class="string"><span class="delimiter">'</span><span class="content">text/xml</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">application/xml</span><span class="delimiter">'</span></span>]
]</code></pre>
</div>
</div>
<div class="paragraph">
<p>See the section on <a href="theWebLayer.html#contentNegotiation">Configuring Mime Types</a> in the user guide for more information.</p>
</div>
<div class="paragraph">
<p>Instead of using the file extension in the URI, you can also obtain a JSON response using the ACCEPT header. Here&#8217;s an example using the Unix <code>curl</code> tool:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ curl -i -H &quot;Accept: application/json&quot; localhost:8080/books/1
{&quot;id&quot;:1,&quot;title&quot;:&quot;The Stand&quot;}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This works thanks to Grails' <a href="theWebLayer.html#contentNegotiation">Content Negotiation</a> features.</p>
</div>
<div class="paragraph">
<p>You can create a new resource by issuing a <code>POST</code> request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ curl -i -X POST -H &quot;Content-Type: application/json&quot; -d '{&quot;title&quot;:&quot;Along Came A Spider&quot;}' localhost:8080/books
HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>Updating can be done with a <code>PUT</code> request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ curl -i -X PUT -H &quot;Content-Type: application/json&quot; -d '{&quot;title&quot;:&quot;Along Came A Spider&quot;}' localhost:8080/books/1
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>Finally a resource can be deleted with <code>DELETE</code> request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ curl -i -X DELETE localhost:8080/books/1
HTTP/1.1 204 No Content
Server: Apache-Coyote/1.1
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>As you can see, the <code>Resource</code> transformation enables all of the HTTP method verbs on the resource. You can enable only read-only capabilities by setting the <code>readOnly</code> attribute to true:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.*</span>

<span class="annotation">@Resource</span>(uri=<span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>, readOnly=<span class="predefined-constant">true</span>)
<span class="type">class</span> <span class="class">Book</span> {
    ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In this case <code>POST</code>, <code>PUT</code> and <code>DELETE</code> requests will be forbidden.</p>
</div>


<h2 id="urlMappings">10.1.2 Mapping to REST resources</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/urlMappings.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>If you prefer to keep the declaration of the URL mapping in your <code>UrlMappings.groovy</code> file then simply removing the <code>uri</code> attribute of the <code>Resource</code> transformation and adding the following line to <code>UrlMappings.groovy</code> will suffice:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="string"><span class="delimiter">&quot;</span><span class="content">/books</span><span class="delimiter">&quot;</span></span>(<span class="key">resources</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">book</span><span class="delimiter">&quot;</span></span>)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Extending your API to include more end points then becomes trivial:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="string"><span class="delimiter">&quot;</span><span class="content">/books</span><span class="delimiter">&quot;</span></span>(<span class="key">resources</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">book</span><span class="delimiter">&quot;</span></span>) {
    <span class="string"><span class="delimiter">&quot;</span><span class="content">/publisher</span><span class="delimiter">&quot;</span></span>(<span class="key">controller</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">publisher</span><span class="delimiter">&quot;</span></span>, <span class="key">method</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">GET</span><span class="delimiter">&quot;</span></span>)
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above example will expose the URI <code>/books/1/publisher</code>.</p>
</div>
<div class="paragraph">
<p>A more detailed explanation on <a href="theWebLayer.html#restfulMappings">creating RESTful URL mappings</a> can be found in the <a href="theWebLayer.html#urlmappings">URL Mappings section</a> of the user guide.</p>
</div>


<h2 id="linkingToResources">10.1.3 Linking to REST resources from GSP pages</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/linkingToResources.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>The <code>link</code> tag offers an easy way to link to any domain class resource:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;g:link</span> <span class="attribute-name">resource</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">${book}</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>My Link<span class="tag">&lt;/g:link&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>However, currently you cannot use g:link to link to the DELETE action and most browsers do not support sending the DELETE method directly.</p>
</div>
<div class="paragraph">
<p>The best way to accomplish this is to use a form submit:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;form</span> <span class="attribute-name">action</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">/book/2</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">method</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">post</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
         <span class="tag">&lt;input</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">hidden</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">_method</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">DELETE</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/form&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Grails supports overriding the request method via the hidden <code>_method</code> parameter. This is for browser compatibility purposes. This is useful when using restful resource mappings to create powerful web interfaces.
To make a link fire this type of event, perhaps capture all click events for links with a <code>data-method</code> attribute and issue a form submit via JavaScript.</p>
</div>


<h2 id="versioningResources">10.1.4 Versioning REST resources</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/versioningResources.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>A common requirement with a REST API is to expose different versions at the same time. There are a few ways this can be achieved in Grails.</p>
</div>
<div class="sect3">
<h4 id="_versioning_using_the_uri">Versioning using the URI</h4>
<div class="paragraph">
<p>A common approach is to use the URI to version APIs (although this approach is discouraged in favour of Hypermedia). For example, you can define the following URL mappings:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="string"><span class="delimiter">&quot;</span><span class="content">/books/v1</span><span class="delimiter">&quot;</span></span>(<span class="key">resources</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">book</span><span class="delimiter">&quot;</span></span>, <span class="key">namespace</span>:<span class="string"><span class="delimiter">'</span><span class="content">v1</span><span class="delimiter">'</span></span>)
<span class="string"><span class="delimiter">&quot;</span><span class="content">/books/v2</span><span class="delimiter">&quot;</span></span>(<span class="key">resources</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">book</span><span class="delimiter">&quot;</span></span>, <span class="key">namespace</span>:<span class="string"><span class="delimiter">'</span><span class="content">v2</span><span class="delimiter">'</span></span>)</code></pre>
</div>
</div>
<div class="paragraph">
<p>That will match the following controllers:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> myapp.v1

<span class="type">class</span> <span class="class">BookController</span> {
    <span class="directive">static</span> namespace = <span class="string"><span class="delimiter">'</span><span class="content">v1</span><span class="delimiter">'</span></span>
}

<span class="keyword">package</span> myapp.v2

<span class="type">class</span> <span class="class">BookController</span> {
    <span class="directive">static</span> namespace = <span class="string"><span class="delimiter">'</span><span class="content">v2</span><span class="delimiter">'</span></span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This approach has the disadvantage of requiring two different URI namespaces for your API.</p>
</div>
</div>
<div class="sect3">
<h4 id="_versioning_with_the_accept_version_header">Versioning with the Accept-Version header</h4>
<div class="paragraph">
<p>As an alternative Grails supports the passing of an <code>Accept-Version</code> header from clients. For example you can define the following URL mappings:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="string"><span class="delimiter">&quot;</span><span class="content">/books</span><span class="delimiter">&quot;</span></span>(<span class="key">version</span>:<span class="string"><span class="delimiter">'</span><span class="content">1.0</span><span class="delimiter">'</span></span>, <span class="key">resources</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">book</span><span class="delimiter">&quot;</span></span>, <span class="key">namespace</span>:<span class="string"><span class="delimiter">'</span><span class="content">v1</span><span class="delimiter">'</span></span>)
<span class="string"><span class="delimiter">&quot;</span><span class="content">/books</span><span class="delimiter">&quot;</span></span>(<span class="key">version</span>:<span class="string"><span class="delimiter">'</span><span class="content">2.0</span><span class="delimiter">'</span></span>, <span class="key">resources</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">book</span><span class="delimiter">&quot;</span></span>, <span class="key">namespace</span>:<span class="string"><span class="delimiter">'</span><span class="content">v2</span><span class="delimiter">'</span></span>)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then in the client simply pass which version you need using the <code>Accept-Version</code> header:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ curl -i -H &quot;Accept-Version: 1.0&quot; -X GET http://localhost:8080/books</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_versioning_using_hypermedia_mime_types">Versioning using Hypermedia / Mime Types</h4>
<div class="paragraph">
<p>Another approach to versioning is to use Mime Type definitions to declare the version of your custom media types (see the section on "Hypermedia as the Engine of Application State" for more information about Hypermedia concepts). For example, in <code>application.groovy</code> you can declare a custom Mime Type for your resource that includes a version parameter (the 'v' parameter):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">grails.mime.types = [
    <span class="key">all</span>: <span class="string"><span class="delimiter">'</span><span class="content">*/*</span><span class="delimiter">'</span></span>,
    <span class="key">book</span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/vnd.books.org.book+json;v=1.0</span><span class="delimiter">&quot;</span></span>,
    <span class="key">bookv2</span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/vnd.books.org.book+json;v=2.0</span><span class="delimiter">&quot;</span></span>,
    ...
}</code></pre>
</div>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
It is critical that place your new mime types after the 'all' Mime Type because if the Content Type of the request cannot be established then the first entry in the map is used for the response. If you have your new Mime Type at the top then Grails will always try and send back your new Mime Type if the requested Mime Type cannot be established.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Then override the renderer (see the section on "Customizing Response Rendering" for more information on custom renderers) to send back the custom Mime Type in <code>grails-app/conf/spring/resourses.groovy</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.render.json.*</span>
<span class="keyword">import</span> <span class="include">grails.web.mime.*</span>

beans = {
    bookRendererV1(JsonRenderer, myapp.v1.Book, <span class="keyword">new</span> MimeType(<span class="string"><span class="delimiter">&quot;</span><span class="content">application/vnd.books.org.book+json</span><span class="delimiter">&quot;</span></span>, [<span class="key">v</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">1.0</span><span class="delimiter">&quot;</span></span>]))
    bookRendererV2(JsonRenderer, myapp.v2.Book, <span class="keyword">new</span> MimeType(<span class="string"><span class="delimiter">&quot;</span><span class="content">application/vnd.books.org.book+json</span><span class="delimiter">&quot;</span></span>, [<span class="key">v</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2.0</span><span class="delimiter">&quot;</span></span>]))
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then update the list of acceptable response formats in your controller:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="type">class</span> <span class="class">BookController</span> <span class="directive">extends</span> RestfulController {
    <span class="directive">static</span> responseFormats = [<span class="string"><span class="delimiter">'</span><span class="content">json</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">xml</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">book</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">bookv2</span><span class="delimiter">'</span></span>]

    <span class="comment">// ...</span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then using the <code>Accept</code> header you can specify which version you need using the Mime Type:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="error">$</span> curl -i -H <span class="string"><span class="delimiter">&quot;</span><span class="content">Accept: application/vnd.books.org.book+json;v=1.0</span><span class="delimiter">&quot;</span></span> -X GET <span class="key">http</span>:<span class="comment">//localhost:8080/books</span></code></pre>
</div>
</div>
</div>


<h2 id="restfulControllers">10.1.5 Implementing REST controllers</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/restfulControllers.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>The <code>Resource</code> transformation is a quick way to get started, but typically you&#8217;ll want to customize the controller logic, the rendering of the response or extend the API to include additional actions.</p>
</div>


<h2 id="extendingRestfulController">10.1.5.1 Extending the RestfulController super class</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/restfulControllers/extendingRestfulController.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>The easiest way to get started doing so is to create a new controller for your resource that extends the <code>grails.rest.RestfulController</code> super class. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="type">class</span> <span class="class">BookController</span> <span class="directive">extends</span> RestfulController&lt;<span class="predefined-type">Book</span>&gt; {
    <span class="directive">static</span> responseFormats = [<span class="string"><span class="delimiter">'</span><span class="content">json</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">xml</span><span class="delimiter">'</span></span>]
    BookController() {
        <span class="local-variable">super</span>(<span class="predefined-type">Book</span>)
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>To customize any logic you can just override the appropriate action. The following table provides the names of the action names and the URIs they map to:</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">HTTP Method</th>
<th class="tableblock halign-left valign-top">URI</th>
<th class="tableblock halign-left valign-top">Controller Action</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GET</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">index</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GET</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books/create</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">create</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">POST</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">save</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GET</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books/${id}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">show</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GET</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books/${id}/edit</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">edit</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">PUT</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books/${id}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">update</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">DELETE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books/${id}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">delete</p></td>
</tr>
</tbody>
</table>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The <code>create</code> and <code>edit</code> actions are only needed if the controller exposes an HTML interface.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>As an example, if you have a <a href="theWebLayer.html#restfulMappings">nested resource</a> then you would typically want to query both the parent and the child identifiers. For example, given the following URL mapping:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="string"><span class="delimiter">&quot;</span><span class="content">/authors</span><span class="delimiter">&quot;</span></span>(<span class="key">resources</span>:<span class="string"><span class="delimiter">'</span><span class="content">author</span><span class="delimiter">'</span></span>) {
    <span class="string"><span class="delimiter">&quot;</span><span class="content">/books</span><span class="delimiter">&quot;</span></span>(<span class="key">resources</span>:<span class="string"><span class="delimiter">'</span><span class="content">book</span><span class="delimiter">'</span></span>)
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You could implement the nested controller as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="type">class</span> <span class="class">BookController</span> <span class="directive">extends</span> RestfulController {
    <span class="directive">static</span> responseFormats = [<span class="string"><span class="delimiter">'</span><span class="content">json</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">xml</span><span class="delimiter">'</span></span>]
    BookController() {
        <span class="local-variable">super</span>(<span class="predefined-type">Book</span>)
    }

    <span class="annotation">@Override</span>
    <span class="directive">protected</span> <span class="predefined-type">Book</span> queryForResource(<span class="predefined-type">Serializable</span> id) {
        <span class="predefined-type">Book</span>.where {
            id == id &amp;&amp; author.id == params.authorId
        }.find()
    }

}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The example above subclasses <code>RestfulController</code> and overrides the protected <code>queryForResource</code> method to customize the query for the resource to take into account the parent resource.</p>
</div>
<div class="sect3">
<h4 id="_customizing_data_binding_in_a_restfulcontroller_subclass">Customizing Data Binding In A RestfulController Subclass</h4>
<div class="paragraph">
<p>The RestfulController class contains code which does data binding for actions like <code>save</code> and <code>update</code>.  The class defines a <code>getObjectToBind()</code> method which returns a value which will be used as the source for data binding.  For example, the update action does something like this&#8230;&#8203;</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="type">class</span> <span class="class">RestfulController</span>&lt;T&gt; {

    <span class="keyword">def</span> <span class="function">update</span>() {
        T instance = <span class="comment">// retrieve instance from the database...</span>

        instance.properties = getObjectToBind()

        <span class="comment">// ...</span>
    }

    <span class="comment">// ...</span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>By default the <code>getObjectToBind()</code> method returns the <a href="../ref/Controllers/request.html">request</a> object.  When the <code>request</code> object is used as the binding source, if the request has a body then the body will be parsed and its contents will be used to do the data binding, otherwise the request parameters will be used to do the data binding.  Subclasses of RestfulController may override the <code>getObjectToBind()</code> method and return anything that is a valid binding source, including a <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Map.html">Map</a> or a <a href="http://docs.grails.org/3.2.11/api/grails/databinding/DataBindingSource.html">DataBindingSource</a>.  For most use cases binding the request is appropriate but the <code>getObjectToBind()</code> method allows for changing that behavior where desired.</p>
</div>
</div>
<div class="sect3">
<h4 id="_using_custom_subclass_of_restfulcontroller_with_resource_annotation">Using custom subclass of RestfulController with Resource annotation</h4>
<div class="paragraph">
<p>You can also customize the behaviour of the controller that backs the Resource annotation.</p>
</div>
<div class="paragraph">
<p>The class must provide a constructor that takes a domain class as it&#8217;s argument. The second constructor is required for supporting Resource annotation with readOnly=true.</p>
</div>
<div class="paragraph">
<p>This is a template that can be used for subclassed RestfulController classes used in Resource annotations:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="type">class</span> <span class="class">SubclassRestfulController</span>&lt;T&gt; <span class="directive">extends</span> RestfulController&lt;T&gt; {
    SubclassRestfulController(<span class="predefined-type">Class</span>&lt;T&gt; domainClass) {
        <span class="local-variable">this</span>(domainClass, <span class="predefined-constant">false</span>)
    }

    SubclassRestfulController(<span class="predefined-type">Class</span>&lt;T&gt; domainClass, <span class="type">boolean</span> readOnly) {
        <span class="local-variable">super</span>(domainClass, readOnly)
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can specify the super class of the controller that backs the Resource annotation with the <code>superClass</code> attribute.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.*</span>

<span class="annotation">@Resource</span>(uri=<span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>, superClass=SubclassRestfulController)
<span class="type">class</span> <span class="class">Book</span> {

    <span class="predefined-type">String</span> title

    <span class="directive">static</span> constraints = {
        title <span class="key">blank</span>:<span class="predefined-constant">false</span>
    }
}</code></pre>
</div>
</div>
</div>


<h2 id="restControllersStepByStep">10.1.5.2 Implementing REST Controllers Step by Step</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/restfulControllers/restControllersStepByStep.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>If you don&#8217;t want to take advantage of the features provided by the <code>RestfulController</code> super class, then you can implement each HTTP verb yourself manually. The first step is to create a controller:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="error">$</span> grails create-controller book</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then add some useful imports and enable readOnly by default:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.transaction.*</span>
<span class="keyword">import</span> <span class="include">static</span> <span class="include">org.springframework.http.HttpStatus.*</span>
<span class="keyword">import</span> <span class="include">static</span> <span class="include">org.springframework.http.HttpMethod.*</span>

<span class="annotation">@Transactional</span>(readOnly = <span class="predefined-constant">true</span>)
<span class="type">class</span> <span class="class">BookController</span> {
    ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Recall that each HTTP verb matches a particular Grails action according to the following conventions:</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">HTTP Method</th>
<th class="tableblock halign-left valign-top">URI</th>
<th class="tableblock halign-left valign-top">Controller Action</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GET</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">index</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GET</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books/${id}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">show</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GET</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books/create</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">create</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">GET</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books/${id}/edit</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">edit</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">POST</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">save</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">PUT</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books/${id}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">update</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">DELETE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">/books/${id}</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">delete</p></td>
</tr>
</tbody>
</table>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The <code>create</code> and <code>edit</code> actions are already required if you plan to implement an HTML interface for the REST resource. They are there in order to render appropriate HTML forms to create and edit a resource. They can be discarded if that is not a requirement.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The key to implementing REST actions is the <a href="../ref/Controllers/respond.html">respond</a> method introduced in Grails 2.3. The <code>respond</code> method tries to produce the most appropriate response for the requested content type (JSON, XML, HTML etc.)</p>
</div>
<div class="sect3">
<h4 id="_implementing_the_index_action">Implementing the 'index' action</h4>
<div class="paragraph">
<p>For example, to implement the <code>index</code> action, simply call the <code>respond</code> method passing the list of objects to respond with:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> <span class="function">index</span>(<span class="predefined-type">Integer</span> max) {
    params.max = <span class="predefined-type">Math</span>.min(max ?: <span class="integer">10</span>, <span class="integer">100</span>)
    respond <span class="predefined-type">Book</span>.list(params), <span class="key">model</span>:[<span class="key">bookCount</span>: <span class="predefined-type">Book</span>.count()]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that in the above example we also use the <code>model</code> argument of the <code>respond</code> method to supply the total count. This is only required if you plan to support pagination via some user interface.</p>
</div>
<div class="paragraph">
<p>The <code>respond</code> method will, using <a href="theWebLayer.html#contentNegotiation">Content Negotiation</a>, attempt to reply with the most appropriate response given the content type requested by the client (via the ACCEPT header or file extension).</p>
</div>
<div class="paragraph">
<p>If the content type is established to be HTML then a model will be produced such that the action above would be the equivalent of writing:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> <span class="function">index</span>(<span class="predefined-type">Integer</span> max) {
    params.max = <span class="predefined-type">Math</span>.min(max ?: <span class="integer">10</span>, <span class="integer">100</span>)
    [<span class="key">bookList</span>: <span class="predefined-type">Book</span>.list(params), <span class="key">bookCount</span>: <span class="predefined-type">Book</span>.count()]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>By providing an <code>index.gsp</code> file you can render an appropriate view for the given model. If the content type is something other than HTML then the <code>respond</code> method will attempt to lookup an appropriate <code>grails.rest.render.Renderer</code> instance that is capable of rendering the passed object. This is done by inspecting the <code>grails.rest.render.RendererRegistry</code>.</p>
</div>
<div class="paragraph">
<p>By default there are already renderers configured for JSON and XML, to find out how to register a custom renderer see the section on "Customizing Response Rendering".</p>
</div>
</div>
<div class="sect3">
<h4 id="_implementing_the_show_action">Implementing the 'show' action</h4>
<div class="paragraph">
<p>The <code>show</code> action, which is used to display and individual resource by id, can be implemented in one line of Groovy code (excluding the method signature):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> <span class="function">show</span>(<span class="predefined-type">Book</span> book) {
    respond book
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>By specifying the domain instance as a parameter to the action Grails will automatically attempt to lookup the domain instance using the <code>id</code> parameter of the request. If the domain instance doesn&#8217;t exist, then <code>null</code> will be passed into the action. The <code>respond</code> method will return a 404 error if null is passed otherwise once again it will attempt to render an appropriate response. If the format is HTML then an appropriate model will produced. The following action is functionally equivalent to the above action:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> <span class="function">show</span>(<span class="predefined-type">Book</span> book) {
    <span class="keyword">if</span>(book == <span class="predefined-constant">null</span>) {
        render <span class="key">status</span>:<span class="integer">404</span>
    }
    <span class="keyword">else</span> {
        <span class="keyword">return</span> [<span class="key">book</span>: book]
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_implementing_the_save_action">Implementing the 'save' action</h4>
<div class="paragraph">
<p>The <code>save</code> action creates new resource representations. To start off, simply define an action that accepts a resource as the first argument and mark it as <code>Transactional</code> with the <code>grails.transaction.Transactional</code> transform:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="annotation">@Transactional</span>
<span class="keyword">def</span> <span class="function">save</span>(<span class="predefined-type">Book</span> book) {
    ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then the first thing to do is check whether the resource has any <a href="validation.html">validation errors</a> and if so respond with the errors:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">if</span>(book.hasErrors()) {
    respond book.errors, <span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">create</span><span class="delimiter">'</span></span>
}
<span class="keyword">else</span> {
    ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the case of HTML the 'create' view will be rendered again so the user can correct the invalid input. In the case of other formats (JSON, XML etc.), the errors object itself will be rendered in the appropriate format and a status code of 422 (UNPROCESSABLE_ENTITY) returned.</p>
</div>
<div class="paragraph">
<p>If there are no errors then the resource can be saved and an appropriate response sent:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">book.save <span class="key">flush</span>:<span class="predefined-constant">true</span>
    withFormat {
        html {
            flash.message = message(<span class="key">code</span>: <span class="string"><span class="delimiter">'</span><span class="content">default.created.message</span><span class="delimiter">'</span></span>, <span class="key">args</span>: [message(<span class="key">code</span>: <span class="string"><span class="delimiter">'</span><span class="content">book.label</span><span class="delimiter">'</span></span>, <span class="keyword">default</span>: <span class="string"><span class="delimiter">'</span><span class="content">Book</span><span class="delimiter">'</span></span>), book.id])
            redirect book
        }
        <span class="string"><span class="delimiter">'</span><span class="content">*</span><span class="delimiter">'</span></span> { render <span class="key">status</span>: CREATED }
    }</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the case of HTML a redirect is issued to the originating resource and for other formats a status code of 201 (CREATED) is returned.</p>
</div>
</div>
<div class="sect3">
<h4 id="_implementing_the_update_action">Implementing the 'update' action</h4>
<div class="paragraph">
<p>The <code>update</code> action updates an existing resource representation and is largely similar to the <code>save</code> action. First define the method signature:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="annotation">@Transactional</span>
<span class="keyword">def</span> <span class="function">update</span>(<span class="predefined-type">Book</span> book) {
    ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the resource exists then Grails will load the resource, otherwise null is passed. In the case of null, you should return a 404:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">if</span>(book == <span class="predefined-constant">null</span>) {
        render <span class="key">status</span>: NOT_FOUND
    }
    <span class="keyword">else</span> {
        ...
    }</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then once again check for errors <a href="validation.html">validation errors</a> and if so respond with the errors:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">if</span>(book.hasErrors()) {
    respond book.errors, <span class="key">view</span>:<span class="string"><span class="delimiter">'</span><span class="content">edit</span><span class="delimiter">'</span></span>
}
<span class="keyword">else</span> {
    ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the case of HTML the 'edit' view will be rendered again so the user can correct the invalid input. In the case of other formats (JSON, XML etc.) the errors object itself will be rendered in the appropriate format and a status code of 422 (UNPROCESSABLE_ENTITY) returned.</p>
</div>
<div class="paragraph">
<p>If there are no errors then the resource can be saved and an appropriate response sent:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">book.save <span class="key">flush</span>:<span class="predefined-constant">true</span>
withFormat {
    html {
        flash.message = message(<span class="key">code</span>: <span class="string"><span class="delimiter">'</span><span class="content">default.updated.message</span><span class="delimiter">'</span></span>, <span class="key">args</span>: [message(<span class="key">code</span>: <span class="string"><span class="delimiter">'</span><span class="content">book.label</span><span class="delimiter">'</span></span>, <span class="keyword">default</span>: <span class="string"><span class="delimiter">'</span><span class="content">Book</span><span class="delimiter">'</span></span>), book.id])
        redirect book
    }
    <span class="string"><span class="delimiter">'</span><span class="content">*</span><span class="delimiter">'</span></span> { render <span class="key">status</span>: OK }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the case of HTML a redirect is issued to the originating resource and for other formats a status code of 200 (OK) is returned.</p>
</div>
</div>
<div class="sect3">
<h4 id="_implementing_the_delete_action">Implementing the 'delete' action</h4>
<div class="paragraph">
<p>The <code>delete</code> action deletes an existing resource. The implementation is largely similar to the <code>update</code> action, except the <code>delete()</code> method is called instead:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">book.delete <span class="key">flush</span>:<span class="predefined-constant">true</span>
withFormat {
    html {
        flash.message = message(<span class="key">code</span>: <span class="string"><span class="delimiter">'</span><span class="content">default.deleted.message</span><span class="delimiter">'</span></span>, <span class="key">args</span>: [message(<span class="key">code</span>: <span class="string"><span class="delimiter">'</span><span class="content">Book.label</span><span class="delimiter">'</span></span>, <span class="keyword">default</span>: <span class="string"><span class="delimiter">'</span><span class="content">Book</span><span class="delimiter">'</span></span>), book.id])
        redirect <span class="key">action</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">index</span><span class="delimiter">&quot;</span></span>, <span class="key">method</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">GET</span><span class="delimiter">&quot;</span></span>
    }
    <span class="string"><span class="delimiter">'</span><span class="content">*</span><span class="delimiter">'</span></span>{ render <span class="key">status</span>: NO_CONTENT }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Notice that for an HTML response a redirect is issued back to the <code>index</code> action, whilst for other content types a response code 204 (NO_CONTENT) is returned.</p>
</div>
</div>


<h2 id="generatingRestControllers">10.1.5.3 Generating a REST controller using scaffolding</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/restfulControllers/generatingRestControllers.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>To see some of these concepts in action and help you get going, the <a href="http://grails.org/plugins.html#plugin/scaffolding">Scaffolding plugin</a>, version 2.0 and above, can generate a REST ready controller for you, simply run the command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ grails generate-controller &lt;&lt;Domain Class Name&gt;&gt;</code></pre>
</div>
</div>


<h2 id="restProfile">10.1.6 The REST Profile</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/restProfile.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>Since Grails 3.1, Grails supports a tailored profile for creating REST applications that provides a more focused set of dependencies and commands.</p>
</div>
<div class="paragraph">
<p>To get started with the REST profile, create an application specifying <code>rest-api</code> as the name of the profile:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ grails create-app my-api --profile rest-api</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will create a new REST application that provides the following features:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Default set of commands for creating and generating REST endpoints</p>
</li>
<li>
<p>Defaults to using JSON views for rendering responses (see the next section)</p>
</li>
<li>
<p>Few plugins than the default Grails plugin (no GSP, no Asset Pipeline, nothing HTML related)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>You will notice for example in the <code>grails-app/views</code> directory that there are <code>*.gson</code> files for rendering the default index page and as well as any 404 and 500 errors.</p>
</div>
<div class="paragraph">
<p>If you issue the following set of commands:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ grails create-domain-class my.api.Book
$ grails generate-all my.api.Book</code></pre>
</div>
</div>
<div class="paragraph">
<p>Instead of CRUD HTML interface a REST endpoint is generated that produces JSON responses. In addition, the generated functional and unit tests by default test the REST endpoint.</p>
</div>


<h2 id="angularJsProfile">10.1.7 The AngularJS Profile</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/angularJsProfile.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>Since Grails 3.1, Grails supports a profile for creating applications with AngularJS that provides a more focused set of dependencies and commands. The angular profile inherits from the REST profile and therefore has all of the commands and properties that the REST profile has.</p>
</div>
<div class="paragraph">
<p>To get started with the AngularJS profile, create an application specifying <code>angularjs</code> as the name of the profile:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ grails create-app my-api --profile angularjs</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will create a new Grails application that provides the following features:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Default set of commands for creating AngularJS artefacts</p>
</li>
<li>
<p>Gradle plugin to manage client side dependencies</p>
</li>
<li>
<p>Gradle plugin to execute client side unit tests</p>
</li>
<li>
<p>Asset Pipeline plugins to ease development</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>By default the AngularJS profile includes GSP support in order to render the index page. This is necessary because the profile is designed around asset pipeline.</p>
</div>
<div class="paragraph">
<p>The new commands are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>create-ng-component</code></p>
</li>
<li>
<p><code>create-ng-controller</code></p>
</li>
<li>
<p><code>create-ng-directive</code></p>
</li>
<li>
<p><code>create-ng-domain</code></p>
</li>
<li>
<p><code>create-ng-module</code></p>
</li>
<li>
<p><code>create-ng-service</code></p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="_project_structure">Project structure</h4>
<div class="paragraph">
<p>The AngularJS profile is designed around a specific project structure. The <code>create-ng</code> commands will automatically create modules where they do not exist.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ grails create-ng-controller foo</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will produce a <code>fooController.js</code> file in <code>grails-app/assets/javascripts/${default package name}/controllers</code>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
By default the angularjs profile will create files in the <code>javascripts</code> directory. You can change that behavior in your configuration with the key <code>grails.codegen.angular.assetDir</code>.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ grails create-ng-domain foo.bar</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will produce a <code>Bar.js</code> file in <code>grails-app/assets/javascripts/foo/domains</code>. It will also create the "foo" module if it does not already exist.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ grails create-ng-module foo.bar</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will produce a <code>foo.bar.js</code> file in <code>grails-app/assets/javascripts/foo/bar</code>. Note the naming convention for modules is different than other artefacts.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ grails create-ng-service foo.bar --type constant</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will produce a <code>bar.js</code> file in <code>grails-app/assets/javascripts/foo/services</code>. It will also create the "foo" module if it does not already exist. The <code>create-ng-service</code> command accepts a flag <code>-type</code>. The types that can be used are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>service</p>
</li>
<li>
<p>factory <em>default</em></p>
</li>
<li>
<p>value</p>
</li>
<li>
<p>provider</p>
</li>
<li>
<p>constant</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Along with the artefacts themselves, the profile will also produce a skeleton unit test file under <code>src/test/javascripts</code> for each create command.</p>
</div>
</div>
<div class="sect3">
<h4 id="_client_side_dependencies">Client side dependencies</h4>
<div class="paragraph">
<p>The <a href="https://github.com/craigburke/bower-installer-gradle">Gradle Bower Plugin</a> is used to manage dependencies with bower. Visit the plugin documentation to learn how to use the plugin.</p>
</div>
</div>
<div class="sect3">
<h4 id="_unit_testing">Unit Testing</h4>
<div class="paragraph">
<p>The <a href="https://github.com/craigburke/karma-gradle">Gradle Karma Plugin</a> is used to execute client side unit tests. All generated tests are written with Jasmine. Visit the plugin documentation to learn how to use the plugin.</p>
</div>
</div>
<div class="sect3">
<h4 id="_asset_pipeline">Asset Pipeline</h4>
<div class="paragraph">
<p>The AngularJS profile includes several asset pipeline plugins to make development easier.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://github.com/craigburke/js-closure-wrap-asset-pipeline">JS Closure Wrap Asset Pipeline</a> will wrap your Angular code in immediately invoked function expressions.</p>
</li>
<li>
<p><a href="https://github.com/craigburke/angular-annotate-asset-pipeline">Annotate Asset Pipeline</a> will annotate your dependencies to be safe for minification.</p>
</li>
<li>
<p><a href="https://github.com/craigburke/angular-template-asset-pipeline">Template Asset Pipeline</a> will put your templates into the <code>$templateCache</code> to prevent http requests to retrieve the templates.</p>
</li>
</ul>
</div>
</div>


<h2 id="angularProfile">10.1.8 The Angular Profile</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/angularProfile.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>Since Grails 3.2.1, Grails supports a profile for creating applications with Angular that provides a more future facing setup.</p>
</div>
<div class="paragraph">
<p>The biggest change in this profile is that the profile creates a multi project gradle build. This is the first profile to have done so. The Angular profile relies on the <a href="https://github.com/angular/angular-cli">Angular CLI</a> to manage the client side application. The server side application is the same as an application created with the <code>rest-api</code> profile.</p>
</div>
<div class="paragraph">
<p>To get started with the Angular profile, create an application specifying <code>angular</code> as the name of the profile:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ grails create-app my-app --profile angular</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will create a <code>my-app</code> directory with the following contents:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>client/
gradle/
gradlew
gradlew.bat
server/
settings.gradle</code></pre>
</div>
</div>
<div class="paragraph">
<p>The entire client application lives in the <code>client</code> folder and the entire server application lives in the <code>server</code> folder.</p>
</div>
<div class="sect3">
<h4 id="_prerequisites">Prerequisites</h4>
<div class="paragraph">
<p>To use this profile, you should have Node, NPM, and the Angular CLI installed. Node should be at least version 5 and NPM should be at least version 3.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://docs.npmjs.com/getting-started/installing-node">Node &amp;&amp; NPM</a></p>
</li>
<li>
<p><a href="https://github.com/angular/angular-cli#installation">Angular CLI</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_project_structure">Project Structure</h4>
<div class="paragraph">
<p>The Angular profile is designed to be used with the <a href="https://github.com/angular/angular-cli">Angular CLI</a>. The CLI was used to create the client application side of the profile to start with. The CLI provides commands to do most of the things you would want to do with the client application, including creating components or services. Because of that, the profile itself provides no commands to do those same things.</p>
</div>
</div>
<div class="sect3">
<h4 id="_running_the_app">Running The App</h4>
<div class="paragraph">
<p>To execute the server side application only, you can execute the <code>bootRun</code> task in the <code>server</code> project:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">./gradlew server:bootRun</code></pre>
</div>
</div>
<div class="paragraph">
<p>The same can be done for the client application:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">./gradlew client:bootRun</code></pre>
</div>
</div>
<div class="paragraph">
<p>To execute both, you must do so in parallel:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">./gradlew bootRun --parallel</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
It is necessary to do so in parallel because by default Gradle executes tasks synchronously, and neither of the <code>bootRun</code> tasks will "finish".
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_testing">Testing</h4>
<div class="paragraph">
<p>The default client application that comes with the profile provides some tests that can be executed. To execute tests in the application:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">./gradlew test</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>test</code> task will execute unit tests with Karma and Jasmine.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">./gradlew integrationTest</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>integrationTest</code> task will execute e2e tests with Protractor.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
You can execute the <code>test</code> and <code>integrationTest</code> tasks on each of the sub-projects the same as you would <code>bootRun</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_cors">CORS</h4>
<div class="paragraph">
<p>Because the client side and server side will be running on separate ports, CORS configuration is required. By default the profile will configure the server side to allow CORS from all hosts via the following config:</p>
</div>
<div class="listingblock">
<div class="title">server/grails-app/conf/application.yml</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">grails</span>:
    <span class="key">cors</span>:
        <span class="key">enabled</span>: <span class="string"><span class="content">true</span></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>See the section on <a href="theWebLayer.html#cors">CORS</a> in the user guide for information on configuring this feature for your needs.</p>
</div>
</div>


<h2 id="jsonViews">10.1.9 JSON Views</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/jsonViews.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>As mentioned in the previous section the REST profile by default uses JSON views to render JSON responses. These play a similar role to GSP, but instead are optimized for outputing JSON responses instead of HTML.</p>
</div>
<div class="paragraph">
<p>You can continue to separate your application in terms of MVC, with the logic of your application residing in controllers and services, whilst view related matters are handled by JSON views.</p>
</div>
<div class="paragraph">
<p>JSON views also provide the flexibility to easily customize the JSON presented to clients without having to resort to relatively complex marshalling libraries like Jackson or Grails' marshaller API.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Since Grails 3.1, JSON views are considered by the Grails team the best way to present JSON output for the client, the section on writing custom marshallers has been removed from the user guide. If you are looking for information on that topic, see <a href="http://grails.github.io/grails-doc/3.0.x/guide/webServices.html#objectMarshallers">the Grails 3.0.x guide</a>.
</td>
</tr>
</table>
</div>


<h2 id="jsonViewsSetup">10.1.9.1 Getting Started</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/jsonViews/jsonViewsSetup.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>If you are using the REST or AngularJS profiles then the JSON views plugin will already be included and you can skip the remainder of this section. Otherwise you will need to modify your <code>build.gradle</code> to include the necessary plugin to activate JSON views:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">compile <span class="string"><span class="delimiter">'</span><span class="content">org.grails.plugins:views-json:1.0.0</span><span class="delimiter">'</span></span> <span class="comment">// or whatever is the latest version</span></code></pre>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The <a href="https://github.com/grails/grails-views">source code repository for JSON views</a> can be found on Github if you are looking for more documentation and contributions
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>In order to compile JSON views for production deployment you should also activate the Gradle plugin by first modifying the <code>buildscript</code> block:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">buildscript {
    ...
    dependencies {
        ...
        classpath <span class="string"><span class="delimiter">&quot;</span><span class="content">org.grails.plugins:views-gradle:1.0.0</span><span class="delimiter">&quot;</span></span>
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then apply the <code>org.grails.plugins.views-json</code> Gradle plugin after any Grails core gradle plugins:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">...
apply <span class="key">plugin</span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">org.grails.grails-web</span><span class="delimiter">&quot;</span></span>
apply <span class="key">plugin</span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">org.grails.plugins.views-json</span><span class="delimiter">&quot;</span></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This will add a <code>compileGsonViews</code> task to Gradle, which is invoked prior to creating the production JAR or WAR file.</p>
</div>


<h2 id="jsonViewsCreating">10.1.9.2 Creating JSON Views</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/jsonViews/jsonViewsCreating.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>JSON views go into the <code>grails-app/views</code> directory and end with the <code>.gson</code> suffix. They are regular Groovy scripts and can be opened in any Groovy editor.</p>
</div>
<div class="paragraph">
<p>Example JSON view:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">json.person {
    name <span class="string"><span class="delimiter">&quot;</span><span class="content">bob</span><span class="delimiter">&quot;</span></span>
}</code></pre>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
To open them in the Groovy editor in Intellij IDEA, double click on the file and when asked which file to associate it with, choose "Groovy"
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The above JSON view produces:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="json">{<span class="key"><span class="delimiter">&quot;</span><span class="content">person</span><span class="delimiter">&quot;</span></span>:{<span class="key"><span class="delimiter">&quot;</span><span class="content">name</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">bob</span><span class="delimiter">&quot;</span></span>}}</code></pre>
</div>
</div>
<div class="paragraph">
<p>There is an implicit <code>json</code> variable which is an instance of <a href="http://docs.groovy-lang.org/latest/html/api/groovy/json/StreamingJsonBuilder.html">StreamingJsonBuilder</a>.</p>
</div>
<div class="paragraph">
<p>Example usages:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">json(<span class="integer">1</span>,<span class="integer">2</span>,<span class="integer">3</span>) == <span class="string"><span class="delimiter">&quot;</span><span class="content">[1,2,3]</span><span class="delimiter">&quot;</span></span>
json { name <span class="string"><span class="delimiter">&quot;</span><span class="content">Bob</span><span class="delimiter">&quot;</span></span> } == <span class="string"><span class="delimiter">'</span><span class="content">{&quot;name&quot;:&quot;Bob&quot;}</span><span class="delimiter">'</span></span>
json([<span class="integer">1</span>,<span class="integer">2</span>,<span class="integer">3</span>]) { n <span class="local-variable">it</span> } == <span class="string"><span class="delimiter">'</span><span class="content">[{&quot;n&quot;:1},{&quot;n&quot;:2},{&quot;n&quot;:3}]</span><span class="delimiter">'</span></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Refer to the API documentation on <a href="http://docs.groovy-lang.org/latest/html/api/groovy/json/StreamingJsonBuilder.html">StreamingJsonBuilder</a> for more information about what is possible.</p>
</div>


<h2 id="jsonViewsAndTemplates">10.1.9.3 JSON View Templates</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/jsonViews/jsonViewsAndTemplates.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>You can define templates starting with underscore <code>_</code>. For example given the following template called <code>_person.gson</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">model {
    Person person
}
json {
    name person.name
    age person.age
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can render it with a view as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">model {
    Family family
}
json {
    name family.father.name
    age family.father.age
    oldestChild g.render(<span class="key">template</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">person</span><span class="delimiter">&quot;</span></span>, <span class="key">model</span>:[<span class="key">person</span>: family.children.max { Person p -&gt; p.age } ])
    children g.render(<span class="key">template</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">person</span><span class="delimiter">&quot;</span></span>, <span class="key">collection</span>: family.children, <span class="key">var</span>:<span class="string"><span class="delimiter">'</span><span class="content">person</span><span class="delimiter">'</span></span>)
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Alternatively for a more concise way to invoke templates, using the tmpl variable:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">model {
    Family family
}
json {
    name family.father.name
    age family.father.age
    oldestChild tmpl.person( family.children.max { Person p -&gt; p.age } ] )
    children tmpl.person( family.children )
}</code></pre>
</div>
</div>


<h2 id="jsonViewsAndDomainClasses">10.1.9.4 Rendering Domain Classes with JSON Views</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/jsonViews/jsonViewsAndDomainClasses.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>Typically your model may involve one or many domain instances. JSON views provide a render method for rendering these.</p>
</div>
<div class="paragraph">
<p>For example given the following domain class:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="type">class</span> <span class="class">Book</span> {
    <span class="predefined-type">String</span> title
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>And the following template:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">model {
    <span class="predefined-type">Book</span> book
}

json g.render(book)</code></pre>
</div>
</div>
<div class="paragraph">
<p>The resulting output is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">{<span class="key">id</span>:<span class="integer">1</span>, <span class="key">title</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">The Stand</span><span class="delimiter">&quot;</span></span>}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can customize the rendering by including or excluding properties:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">json g.render(book, [<span class="key">includes</span>:[<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>]])</code></pre>
</div>
</div>
<div class="paragraph">
<p>Or by providing a closure to add additional JSON output:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">json g.render(book) {
    pages <span class="integer">1000</span>
}</code></pre>
</div>
</div>


<h2 id="jsonViewsTemplatesAndConventions">10.1.9.5 JSON Views by Convention</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/jsonViews/jsonViewsTemplatesAndConventions.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>There are a few useful conventions you can follow when creating JSON views. For example if you have a domain class called <code>Book</code>, then creating a template located at <code>grails-app/views/book/_book.gson</code> and using the <a href="../ref/Controllers/respond.html">respond</a> method will result in rendering the template:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> <span class="function">show</span>(<span class="predefined-type">Long</span> id) {
    respond <span class="predefined-type">Book</span>.get(id)
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In addition if an error occurs during validation by default Grails will try to render a template called <code>grails-app/views/book/_errors.gson</code>, otherwise it will try to render <code>grails-app/views/errors/_errors.gson</code> if the former doesn&#8217;t exist.</p>
</div>
<div class="paragraph">
<p>This is useful because when persisting objects you can <code>respond</code> with validation errors to render these aforementioned templates:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="annotation">@Transactional</span>
<span class="keyword">def</span> <span class="function">save</span>(<span class="predefined-type">Book</span> book) {
    <span class="keyword">if</span> (book.hasErrors()) {
        transactionStatus.setRollbackOnly()
        respond book.errors
    }
    <span class="keyword">else</span> {
        <span class="comment">// valid object</span>
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If a validation error occurs in the above example the <code>grails-app/views/book/_errors.gson</code> template will be rendered.</p>
</div>
<div class="paragraph">
<p>For more information on JSON views (and Markup views), see the <a href="http://views.grails.org/latest/">JSON Views user guide</a>.</p>
</div>


<h2 id="renderers">10.1.10 Customizing Response Rendering</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/renderers.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>If you are looking for a more low-level API and JSON or Markup views don&#8217;t suite your needs then you may want to consider implementing a custom renderer.</p>
</div>


<h2 id="defaultRenderers">10.1.10.1 Customizing the Default Renderers</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/renderers/defaultRenderers.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>The default renderers for XML and JSON can be found in the <code>grails.rest.render.xml</code> and <code>grails.rest.render.json</code> packages respectively. These use the Grails converters (<code>grails.converters.XML</code> and <code>grails.converters.JSON</code>) by default for response rendering.</p>
</div>
<div class="paragraph">
<p>You can easily customize response rendering using these default renderers. A common change you may want to make is to include or exclude certain properties from rendering.</p>
</div>
<div class="sect3">
<h4 id="_including_or_excluding_properties_from_rendering">Including or Excluding Properties from Rendering</h4>
<div class="paragraph">
<p>As mentioned previously, Grails maintains a registry of <code>grails.rest.render.Renderer</code> instances. There are some default configured renderers and the ability to register or override renderers for a given domain class or even for a collection of domain classes. To include a particular property from rendering you need to register a custom renderer by defining a bean in <code>grails-app/conf/spring/resources.groovy</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.render.xml.*</span>

beans = {
    bookRenderer(XmlRenderer, <span class="predefined-type">Book</span>) {
        includes = [<span class="string"><span class="delimiter">'</span><span class="content">title</span><span class="delimiter">'</span></span>]
    }
}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The bean name is not important (Grails will scan the application context for all registered renderer beans), but for organizational and readability purposes it is recommended you name it something meaningful.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>To exclude a property, the <code>excludes</code> property of the <code>XmlRenderer</code> class can be used:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.render.xml.*</span>

beans = {
    bookRenderer(XmlRenderer, <span class="predefined-type">Book</span>) {
        excludes = [<span class="string"><span class="delimiter">'</span><span class="content">isbn</span><span class="delimiter">'</span></span>]
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_customizing_the_converters">Customizing the Converters</h4>
<div class="paragraph">
<p>As mentioned previously, the default renders use the <code>grails.converters</code> package under the covers. In other words, under the covers they essentially do the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.converters.*</span>

...
render book <span class="keyword">as</span> XML

<span class="comment">// or render book as JSON</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Why the separation between converters and renderers? Well a renderer has more flexibility to use whatever rendering technology you chose. When implementing a custom renderer you could use <a href="http://wiki.fasterxml.com/JacksonHome">Jackson</a>, <a href="http://code.google.com/p/google-gson/">Gson</a> or any Java library to implement the renderer. Converters on the other hand are very much tied to Grails' own marshalling implementation.</p>
</div>
</div>


<h2 id="customRenderers">10.1.10.2 Implementing a Custom Renderer</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/renderers/customRenderers.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>If you want even more control of the rendering or prefer to use your own marshalling techniques then you can implement your own <code>Renderer</code> instance. For example below is a simple implementation that customizes the rendering of the <code>Book</code> class:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> myapp
<span class="keyword">import</span> <span class="include">grails.rest.render.*</span>
<span class="keyword">import</span> <span class="include">grails.web.mime.MimeType</span>

<span class="type">class</span> <span class="class">BookXmlRenderer</span> <span class="directive">extends</span> AbstractRenderer&lt;<span class="predefined-type">Book</span>&gt; {
    BookXmlRenderer() {
        <span class="local-variable">super</span>(<span class="predefined-type">Book</span>, [MimeType.XML,MimeType.TEXT_XML] <span class="keyword">as</span> MimeType<span class="type">[]</span>)
    }

    <span class="type">void</span> render(<span class="predefined-type">Book</span> object, <span class="predefined-type">RenderContext</span> context) {
        context.contentType = MimeType.XML.name

        <span class="keyword">def</span> xml = <span class="keyword">new</span> groovy.xml.MarkupBuilder(context.writer)
        xml.book(<span class="key">id</span>: object.id, <span class="key">title</span>:object.title)
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>AbstractRenderer</code> super class has a constructor that takes the class that it renders and the <code>MimeType</code>(s) that are accepted (via the ACCEPT header or file extension) for the renderer.</p>
</div>
<div class="paragraph">
<p>To configure this renderer, simply add it is a bean to <code>grails-app/conf/spring/resources.groovy</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">beans = {
    bookRenderer(myapp.BookXmlRenderer)
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The result will be that all <code>Book</code> instances will be rendered in the following format:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">&lt;book id=<span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span> title=<span class="string"><span class="delimiter">&quot;</span><span class="content">The Stand</span><span class="delimiter">&quot;</span></span>/&gt;</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If you change the rendering to a completely different format like the above, then you also need to change the binding if you plan to support POST and PUT requests. Grails will not automatically know how to bind data from a custom XML format to a domain class otherwise. See the section on "Customizing Binding of Resources" for further information.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="_container_renderers">Container Renderers</h4>
<div class="paragraph">
<p>A <code>grails.rest.render.ContainerRenderer</code> is a renderer that renders responses for containers of objects (lists, maps, collections etc.). The interface is largely the same as the <code>Renderer</code> interface except for the addition of the <code>getComponentType()</code> method, which should return the "contained" type. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="type">class</span> <span class="class">BookListRenderer</span> <span class="directive">implements</span> ContainerRenderer&lt;<span class="predefined-type">List</span>, <span class="predefined-type">Book</span>&gt; {
    <span class="predefined-type">Class</span>&lt;<span class="predefined-type">List</span>&gt; getTargetType() { <span class="predefined-type">List</span> }
    <span class="predefined-type">Class</span>&lt;<span class="predefined-type">Book</span>&gt; getComponentType() { <span class="predefined-type">Book</span> }
    MimeType<span class="type">[]</span> getMimeTypes() { [ MimeType.XML] <span class="keyword">as</span> MimeType<span class="type">[]</span> }
    <span class="type">void</span> render(<span class="predefined-type">List</span> object, <span class="predefined-type">RenderContext</span> context) {
        ....
    }
}</code></pre>
</div>
</div>
</div>


<h2 id="gspRenderers">10.1.10.3 Using GSP to Customize Rendering</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/renderers/gspRenderers.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>You can also customize rendering on a per action basis using Groovy Server Pages (GSP). For example given the <code>show</code> action mentioned previously:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> <span class="function">show</span>(<span class="predefined-type">Book</span> book) {
    respond book
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You could supply a <code>show.xml.gsp</code> file to customize the rendering of the XML:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">&lt;%<span class="annotation">@page</span> contentType=<span class="string"><span class="delimiter">&quot;</span><span class="content">application/xml</span><span class="delimiter">&quot;</span></span>%&gt;
&lt;book id=<span class="string"><span class="delimiter">&quot;</span><span class="inline"><span class="inline-delimiter">${</span>book.id<span class="inline-delimiter">}</span></span><span class="delimiter">&quot;</span></span> title=<span class="string"><span class="delimiter">&quot;</span><span class="inline"><span class="inline-delimiter">${</span>book.title<span class="inline-delimiter">}</span></span><span class="delimiter">&quot;</span></span>/&gt;</code></pre>
</div>
</div>


<h2 id="hypermedia">10.1.11 Hypermedia as the Engine of Application State</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/hypermedia.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p><a href="http://en.wikipedia.org/wiki/HATEOAS">HATEOAS</a>, an abbreviation for Hypermedia as the Engine of Application State, is a common pattern applied to REST architectures that uses hypermedia and linking to define the REST API.</p>
</div>
<div class="paragraph">
<p>Hypermedia (also called Mime or Media Types) are used to describe the state of a REST resource, and links tell clients how to transition to the next state. The format of the response is typically JSON or XML, although standard formats such as <a href="http://tools.ietf.org/html/rfc4287">Atom</a> and/or <a href="http://stateless.co/hal_specification.html">HAL</a> are frequently used.</p>
</div>


<h2 id="hal">10.1.11.1 HAL Support</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/hypermedia/hal.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p><a href="http://stateless.co/hal_specification.html">HAL</a> is a standard exchange format commonly used when developing REST APIs that follow HATEOAS principals. An example HAL document representing a list of orders can be seen below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript">{
    <span class="key"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
        <span class="key"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: { <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">/orders</span><span class="delimiter">&quot;</span></span> },
        <span class="key"><span class="delimiter">&quot;</span><span class="content">next</span><span class="delimiter">&quot;</span></span>: { <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">/orders?page=2</span><span class="delimiter">&quot;</span></span> },
        <span class="key"><span class="delimiter">&quot;</span><span class="content">find</span><span class="delimiter">&quot;</span></span>: {
            <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">/orders{?id}</span><span class="delimiter">&quot;</span></span>,
            <span class="key"><span class="delimiter">&quot;</span><span class="content">templated</span><span class="delimiter">&quot;</span></span>: <span class="predefined-constant">true</span>
        },
        <span class="key"><span class="delimiter">&quot;</span><span class="content">admin</span><span class="delimiter">&quot;</span></span>: [{
            <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">/admins/2</span><span class="delimiter">&quot;</span></span>,
            <span class="key"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Fred</span><span class="delimiter">&quot;</span></span>
        }, {
            <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">/admins/5</span><span class="delimiter">&quot;</span></span>,
            <span class="key"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Kate</span><span class="delimiter">&quot;</span></span>
        }]
    },
    <span class="key"><span class="delimiter">&quot;</span><span class="content">currentlyProcessing</span><span class="delimiter">&quot;</span></span>: <span class="integer">14</span>,
    <span class="key"><span class="delimiter">&quot;</span><span class="content">shippedToday</span><span class="delimiter">&quot;</span></span>: <span class="integer">20</span>,
    <span class="key"><span class="delimiter">&quot;</span><span class="content">_embedded</span><span class="delimiter">&quot;</span></span>: {
        <span class="key"><span class="delimiter">&quot;</span><span class="content">order</span><span class="delimiter">&quot;</span></span>: [{
            <span class="key"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
                <span class="key"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: { <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">/orders/123</span><span class="delimiter">&quot;</span></span> },
                <span class="key"><span class="delimiter">&quot;</span><span class="content">basket</span><span class="delimiter">&quot;</span></span>: { <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">/baskets/98712</span><span class="delimiter">&quot;</span></span> },
                <span class="key"><span class="delimiter">&quot;</span><span class="content">customer</span><span class="delimiter">&quot;</span></span>: { <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">/customers/7809</span><span class="delimiter">&quot;</span></span> }
            },
            <span class="key"><span class="delimiter">&quot;</span><span class="content">total</span><span class="delimiter">&quot;</span></span>: <span class="float">30.00</span>,
            <span class="key"><span class="delimiter">&quot;</span><span class="content">currency</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">USD</span><span class="delimiter">&quot;</span></span>,
            <span class="key"><span class="delimiter">&quot;</span><span class="content">status</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">shipped</span><span class="delimiter">&quot;</span></span>
        }, {
            <span class="key"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
                <span class="key"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: { <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">/orders/124</span><span class="delimiter">&quot;</span></span> },
                <span class="key"><span class="delimiter">&quot;</span><span class="content">basket</span><span class="delimiter">&quot;</span></span>: { <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">/baskets/97213</span><span class="delimiter">&quot;</span></span> },
                <span class="key"><span class="delimiter">&quot;</span><span class="content">customer</span><span class="delimiter">&quot;</span></span>: { <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">/customers/12369</span><span class="delimiter">&quot;</span></span> }
            },
            <span class="key"><span class="delimiter">&quot;</span><span class="content">total</span><span class="delimiter">&quot;</span></span>: <span class="float">20.00</span>,
            <span class="key"><span class="delimiter">&quot;</span><span class="content">currency</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">USD</span><span class="delimiter">&quot;</span></span>,
            <span class="key"><span class="delimiter">&quot;</span><span class="content">status</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">processing</span><span class="delimiter">&quot;</span></span>
        }]
    }
}</code></pre>
</div>
</div>
<div class="sect3">
<h4 id="_exposing_resources_using_hal">Exposing Resources Using HAL</h4>
<div class="paragraph">
<p>To return HAL instead of regular JSON for a resource you can simply override the renderer in <code>grails-app/conf/spring/resources.groovy</code> with an instance of <code>grails.rest.render.hal.HalJsonRenderer</code> (or <code>HalXmlRenderer</code> for the XML variation):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.render.hal.*</span>
beans = {
    halBookRenderer(HalJsonRenderer, rest.test.Book)
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You will also need to update the acceptable response formats for the resource so that the HAL format is included. Not doing so will result in a 406 - Not Acceptable response being returned from the server.</p>
</div>
<div class="paragraph">
<p>This can be done by setting the <code>formats</code> attribute of the <code>Resource</code> transformation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.*</span>

<span class="annotation">@Resource</span>(uri=<span class="string"><span class="delimiter">'</span><span class="content">/books</span><span class="delimiter">'</span></span>, formats=[<span class="string"><span class="delimiter">'</span><span class="content">json</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">xml</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">hal</span><span class="delimiter">'</span></span>])
<span class="type">class</span> <span class="class">Book</span> {
    ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Or by updating the <code>responseFormats</code> in the controller:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="type">class</span> <span class="class">BookController</span> <span class="directive">extends</span> RestfulController {
    <span class="directive">static</span> responseFormats = [<span class="string"><span class="delimiter">'</span><span class="content">json</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">xml</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">hal</span><span class="delimiter">'</span></span>]

    <span class="comment">// ...</span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the bean in place requesting the HAL content type will return HAL:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="error">$</span> curl -i -H <span class="string"><span class="delimiter">&quot;</span><span class="content">Accept: application/hal+json</span><span class="delimiter">&quot;</span></span> <span class="key">http</span>:<span class="comment">//localhost:8080/books/1</span>

HTTP/<span class="float">1.1</span> <span class="integer">200</span> OK
<span class="key">Server</span>: Apache-Coyote/<span class="float">1.1</span>
Content-<span class="predefined-type">Type</span>: application/hal+json;charset=ISO-<span class="integer">8859</span>-<span class="integer">1</span>

{
  <span class="string"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
    <span class="string"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: {
      <span class="string"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8080/books/1</span><span class="delimiter">&quot;</span></span>,
      <span class="string"><span class="delimiter">&quot;</span><span class="content">hreflang</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span>,
      <span class="string"><span class="delimiter">&quot;</span><span class="content">type</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/hal+json</span><span class="delimiter">&quot;</span></span>
    }
  },
  <span class="string"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="char">\&quot;</span><span class="content">The Stand</span><span class="char">\&quot;</span><span class="delimiter">&quot;</span></span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>To use HAL XML format simply change the renderer:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.render.hal.*</span>
beans = {
    halBookRenderer(HalXmlRenderer, rest.test.Book)
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_rendering_collections_using_hal">Rendering Collections Using HAL</h4>
<div class="paragraph">
<p>To return HAL instead of regular JSON for a list of resources you can simply override the renderer in <code>grails-app/conf/spring/resources.groovy</code> with an instance of <code>grails.rest.render.hal.HalJsonCollectionRenderer</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.render.hal.*</span>
beans = {
    halBookCollectionRenderer(HalJsonCollectionRenderer, rest.test.Book)
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the bean in place requesting the HAL content type will return HAL:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="error">$</span> curl -i -H <span class="string"><span class="delimiter">&quot;</span><span class="content">Accept: application/hal+json</span><span class="delimiter">&quot;</span></span> <span class="key">http</span>:<span class="comment">//localhost:8080/books</span>
HTTP/<span class="float">1.1</span> <span class="integer">200</span> OK
<span class="key">Server</span>: Apache-Coyote/<span class="float">1.1</span>
Content-<span class="predefined-type">Type</span>: application/hal+json;charset=UTF-<span class="integer">8</span>
Transfer-<span class="key">Encoding</span>: chunked
<span class="predefined-type">Date</span>: Thu, <span class="integer">17</span> Oct <span class="integer">2013</span> <span class="octal">02</span>:<span class="integer">34</span>:<span class="integer">14</span> GMT

{
  <span class="string"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
    <span class="string"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: {
      <span class="string"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8080/books</span><span class="delimiter">&quot;</span></span>,
      <span class="string"><span class="delimiter">&quot;</span><span class="content">hreflang</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span>,
      <span class="string"><span class="delimiter">&quot;</span><span class="content">type</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/hal+json</span><span class="delimiter">&quot;</span></span>
    }
  },
  <span class="string"><span class="delimiter">&quot;</span><span class="content">_embedded</span><span class="delimiter">&quot;</span></span>: {
    <span class="string"><span class="delimiter">&quot;</span><span class="content">book</span><span class="delimiter">&quot;</span></span>: [
      {
        <span class="string"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
          <span class="string"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: {
            <span class="string"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8080/books/1</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">hreflang</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">type</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/hal+json</span><span class="delimiter">&quot;</span></span>
          }
        },
        <span class="string"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">The Stand</span><span class="delimiter">&quot;</span></span>
      },
      {
        <span class="string"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
          <span class="string"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: {
            <span class="string"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8080/books/2</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">hreflang</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">type</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/hal+json</span><span class="delimiter">&quot;</span></span>
          }
        },
        <span class="string"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Infinite Jest</span><span class="delimiter">&quot;</span></span>
      },
      {
        <span class="string"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
          <span class="string"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: {
            <span class="string"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8080/books/3</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">hreflang</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">type</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/hal+json</span><span class="delimiter">&quot;</span></span>
          }
        },
        <span class="string"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Walden</span><span class="delimiter">&quot;</span></span>
      }
    ]
  }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Notice that the key associated with the list of <code>Book</code> objects in the rendered JSON is <code>book</code> which is derived from the type of objects in the collection, namely <code>Book</code>.  In order to customize the value of this key assign a value to the <code>collectionName</code> property on the <code>HalJsonCollectionRenderer</code> bean as shown below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.render.hal.*</span>
beans = {
    halBookCollectionRenderer(HalCollectionJsonRenderer, rest.test.Book) {
        collectionName = <span class="string"><span class="delimiter">'</span><span class="content">publications</span><span class="delimiter">'</span></span>
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>With that in place the rendered HAL will look like the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="error">$</span> curl -i -H <span class="string"><span class="delimiter">&quot;</span><span class="content">Accept: application/hal+json</span><span class="delimiter">&quot;</span></span> <span class="key">http</span>:<span class="comment">//localhost:8080/books</span>
HTTP/<span class="float">1.1</span> <span class="integer">200</span> OK
<span class="key">Server</span>: Apache-Coyote/<span class="float">1.1</span>
Content-<span class="predefined-type">Type</span>: application/hal+json;charset=UTF-<span class="integer">8</span>
Transfer-<span class="key">Encoding</span>: chunked
<span class="predefined-type">Date</span>: Thu, <span class="integer">17</span> Oct <span class="integer">2013</span> <span class="octal">02</span>:<span class="integer">34</span>:<span class="integer">14</span> GMT

{
  <span class="string"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
    <span class="string"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: {
      <span class="string"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8080/books</span><span class="delimiter">&quot;</span></span>,
      <span class="string"><span class="delimiter">&quot;</span><span class="content">hreflang</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span>,
      <span class="string"><span class="delimiter">&quot;</span><span class="content">type</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/hal+json</span><span class="delimiter">&quot;</span></span>
    }
  },
  <span class="string"><span class="delimiter">&quot;</span><span class="content">_embedded</span><span class="delimiter">&quot;</span></span>: {
    <span class="string"><span class="delimiter">&quot;</span><span class="content">publications</span><span class="delimiter">&quot;</span></span>: [
      {
        <span class="string"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
          <span class="string"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: {
            <span class="string"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8080/books/1</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">hreflang</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">type</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/hal+json</span><span class="delimiter">&quot;</span></span>
          }
        },
        <span class="string"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">The Stand</span><span class="delimiter">&quot;</span></span>
      },
      {
        <span class="string"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
          <span class="string"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: {
            <span class="string"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8080/books/2</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">hreflang</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">type</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/hal+json</span><span class="delimiter">&quot;</span></span>
          }
        },
        <span class="string"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Infinite Jest</span><span class="delimiter">&quot;</span></span>
      },
      {
        <span class="string"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
          <span class="string"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: {
            <span class="string"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8080/books/3</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">hreflang</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">type</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/hal+json</span><span class="delimiter">&quot;</span></span>
          }
        },
        <span class="string"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Walden</span><span class="delimiter">&quot;</span></span>
      }
    ]
  }
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_using_custom_media_mime_types">Using Custom Media / Mime Types</h4>
<div class="paragraph">
<p>If you wish to use a custom Mime Type then you first need to declare the Mime Types in <code>grails-app/conf/application.groovy</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">grails.mime.types = [
    <span class="key">all</span>:      <span class="string"><span class="delimiter">&quot;</span><span class="content">*/*</span><span class="delimiter">&quot;</span></span>,
    <span class="key">book</span>:     <span class="string"><span class="delimiter">&quot;</span><span class="content">application/vnd.books.org.book+json</span><span class="delimiter">&quot;</span></span>,
    <span class="key">bookList</span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/vnd.books.org.booklist+json</span><span class="delimiter">&quot;</span></span>,
    ...
]</code></pre>
</div>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
It is critical that place your new mime types after the 'all' Mime Type because if the Content Type of the request cannot be established then the first entry in the map is used for the response. If you have your new Mime Type at the top then Grails will always try and send back your new Mime Type if the requested Mime Type cannot be established.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Then override the renderer to return HAL using the custom Mime Types:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.render.hal.*</span>
<span class="keyword">import</span> <span class="include">grails.web.mime.*</span>

beans = {
    halBookRenderer(HalJsonRenderer, rest.test.Book, <span class="keyword">new</span> MimeType(<span class="string"><span class="delimiter">&quot;</span><span class="content">application/vnd.books.org.book+json</span><span class="delimiter">&quot;</span></span>, [<span class="key">v</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">1.0</span><span class="delimiter">&quot;</span></span>]))
    halBookListRenderer(HalJsonCollectionRenderer, rest.test.Book, <span class="keyword">new</span> MimeType(<span class="string"><span class="delimiter">&quot;</span><span class="content">application/vnd.books.org.booklist+json</span><span class="delimiter">&quot;</span></span>, [<span class="key">v</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">1.0</span><span class="delimiter">&quot;</span></span>]))
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the above example the first bean defines a HAL renderer for a single book instance that returns a Mime Type of <code>application/vnd.books.org.book+json</code>. The second bean defines the Mime Type used to render a collection of books (in this case <code>application/vnd.books.org.booklist+json</code>).</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<code>application/vnd.books.org.booklist+json</code> is an example of a media-range (<a href="http://www.w3.org/Protocols/rfc2616/rfc2616.html" class="bare">http://www.w3.org/Protocols/rfc2616/rfc2616.html</a> - Header Field Definitions).  This example uses entity (book) and operation (list) to form the media-range values but in reality, it may not be necessary to create a separate Mime type for each operation.  Further, it may not be necessary to create Mime types at the entity level.  See the section on "Versioning REST resources" for further information about how to define your own Mime types.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>With this in place issuing a request for the new Mime Type returns the necessary HAL:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ curl -i -H &quot;Accept: application/vnd.books.org.book+json&quot; http://localhost:8080/books/1

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/vnd.books.org.book+json;charset=ISO-8859-1

{
  &quot;_links&quot;: {
    &quot;self&quot;: {
      &quot;href&quot;: &quot;http://localhost:8080/books/1&quot;,
      &quot;hreflang&quot;: &quot;en&quot;,
      &quot;type&quot;: &quot;application/vnd.books.org.book+json&quot;
    }
  },
  &quot;title&quot;: &quot;\&quot;The Stand\&quot;&quot;
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_customizing_link_rendering">Customizing Link Rendering</h4>
<div class="paragraph">
<p>An important aspect of HATEOAS is the usage of links that describe the transitions the client can use to interact with the REST API. By default the <code>HalJsonRenderer</code> will automatically create links for you for associations and to the resource itself (using the "self" relationship).</p>
</div>
<div class="paragraph">
<p>However you can customize link rendering using the <code>link</code> method that is added to all domain classes annotated with <code>grails.rest.Resource</code> or any class annotated with <code>grails.rest.Linkable</code>. For example, the <code>show</code> action can be modified as follows to provide a new link in the resulting output:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">def</span> <span class="function">show</span>(<span class="predefined-type">Book</span> book) {
    book.link <span class="key">rel</span>:<span class="string"><span class="delimiter">'</span><span class="content">publisher</span><span class="delimiter">'</span></span>, <span class="key">href</span>: g.createLink(<span class="key">absolute</span>: <span class="predefined-constant">true</span>, <span class="key">resource</span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">publisher</span><span class="delimiter">&quot;</span></span>, <span class="key">params</span>:[<span class="key">bookId</span>: book.id])
    respond book
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Which will result in output such as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="javascript">{
  <span class="key"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
    <span class="key"><span class="delimiter">&quot;</span><span class="content">self</span><span class="delimiter">&quot;</span></span>: {
      <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8080/books/1</span><span class="delimiter">&quot;</span></span>,
      <span class="key"><span class="delimiter">&quot;</span><span class="content">hreflang</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span>,
      <span class="key"><span class="delimiter">&quot;</span><span class="content">type</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">application/vnd.books.org.book+json</span><span class="delimiter">&quot;</span></span>
    }
    <span class="string"><span class="delimiter">&quot;</span><span class="content">publisher</span><span class="delimiter">&quot;</span></span>: {
        <span class="key"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8080/books/1/publisher</span><span class="delimiter">&quot;</span></span>,
        <span class="key"><span class="delimiter">&quot;</span><span class="content">hreflang</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">en</span><span class="delimiter">&quot;</span></span>
    }
  },
  <span class="key"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="char">\&quot;</span><span class="content">The Stand</span><span class="char">\&quot;</span><span class="delimiter">&quot;</span></span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>link</code> method can be passed named arguments that match the properties of the <code>grails.rest.Link</code> class.</p>
</div>
</div>


<h2 id="atom">10.1.11.2 Atom Support</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/hypermedia/atom.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p><a href="http://tools.ietf.org/html/rfc4287">Atom</a> is another standard interchange format used to implement REST APIs. An example of Atom output can be seen below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="preprocessor">&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;</span>
<span class="tag">&lt;feed</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http://www.w3.org/2005/Atom</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>

 <span class="tag">&lt;title&gt;</span>Example Feed<span class="tag">&lt;/title&gt;</span>
 <span class="tag">&lt;link</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http://example.org/</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
 <span class="tag">&lt;updated&gt;</span>2003-12-13T18:30:02Z<span class="tag">&lt;/updated&gt;</span>
 <span class="tag">&lt;author&gt;</span>
   <span class="tag">&lt;name&gt;</span>John Doe<span class="tag">&lt;/name&gt;</span>
 <span class="tag">&lt;/author&gt;</span>
 <span class="tag">&lt;id&gt;</span>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6<span class="tag">&lt;/id&gt;</span>

 <span class="tag">&lt;entry&gt;</span>
   <span class="tag">&lt;title&gt;</span>Atom-Powered Robots Run Amok<span class="tag">&lt;/title&gt;</span>
   <span class="tag">&lt;link</span> <span class="attribute-name">href</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">http://example.org/2003/12/13/atom03</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
   <span class="tag">&lt;id&gt;</span>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a<span class="tag">&lt;/id&gt;</span>
   <span class="tag">&lt;updated&gt;</span>2003-12-13T18:30:02Z<span class="tag">&lt;/updated&gt;</span>
   <span class="tag">&lt;summary&gt;</span>Some text.<span class="tag">&lt;/summary&gt;</span>
 <span class="tag">&lt;/entry&gt;</span>

<span class="tag">&lt;/feed&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>To use Atom rendering again simply define a custom renderer:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">import</span> <span class="include">grails.rest.render.atom.*</span>
beans = {
    halBookRenderer(AtomRenderer, rest.test.Book)
    halBookListRenderer(AtomCollectionRenderer, rest.test.Book)
}</code></pre>
</div>
</div>


<h2 id="vndError">10.1.11.3 Vnd.Error Support</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/hypermedia/vndError.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p><a href="https://github.com/blongden/vnd.error">Vnd.Error</a> is a standardised way of expressing an error response.</p>
</div>
<div class="paragraph">
<p>By default when a validation error occurs when attempting to POST new resources then the errors object will be sent back allow with a 422 respond code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="error">$</span> curl -i -H <span class="string"><span class="delimiter">&quot;</span><span class="content">Accept: application/json</span><span class="delimiter">&quot;</span></span>  -H <span class="string"><span class="delimiter">&quot;</span><span class="content">Content-Type: application/json</span><span class="delimiter">&quot;</span></span> -X POST -d <span class="string"><span class="delimiter">&quot;</span><span class="delimiter">&quot;</span></span> <span class="key">http</span>:<span class="comment">//localhost:8080/books</span>

HTTP/<span class="float">1.1</span> <span class="integer">422</span> Unprocessable <span class="predefined-type">Entity</span>
<span class="key">Server</span>: Apache-Coyote/<span class="float">1.1</span>
Content-<span class="predefined-type">Type</span>: application/json;charset=ISO-<span class="integer">8859</span>-<span class="integer">1</span>

{
  <span class="string"><span class="delimiter">&quot;</span><span class="content">errors</span><span class="delimiter">&quot;</span></span>: [
    {
      <span class="string"><span class="delimiter">&quot;</span><span class="content">object</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">rest.test.Book</span><span class="delimiter">&quot;</span></span>,
      <span class="string"><span class="delimiter">&quot;</span><span class="content">field</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>,
      <span class="string"><span class="delimiter">&quot;</span><span class="content">rejected-value</span><span class="delimiter">&quot;</span></span>: <span class="predefined-constant">null</span>,
      <span class="string"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Property [title] of class [class rest.test.Book] cannot be null</span><span class="delimiter">&quot;</span></span>
    }
  ]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you wish to change the format to Vnd.Error then simply register <code>grails.rest.render.errors.VndErrorJsonRenderer</code> bean in <code>grails-app/conf/spring/resources.groovy</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">beans = {
    vndJsonErrorRenderer(grails.rest.render.errors.VndErrorJsonRenderer)
    <span class="comment">// for Vnd.Error XML format</span>
    vndXmlErrorRenderer(grails.rest.render.errors.VndErrorXmlRenderer)
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then if you alter the client request to accept Vnd.Error you get an appropriate response:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="error">$</span> curl -i -H <span class="string"><span class="delimiter">&quot;</span><span class="content">Accept: application/vnd.error+json,application/json</span><span class="delimiter">&quot;</span></span> -H <span class="string"><span class="delimiter">&quot;</span><span class="content">Content-Type: application/json</span><span class="delimiter">&quot;</span></span> -X POST -d <span class="string"><span class="delimiter">&quot;</span><span class="delimiter">&quot;</span></span> <span class="key">http</span>:<span class="comment">//localhost:8080/books</span>
HTTP/<span class="float">1.1</span> <span class="integer">200</span> OK
<span class="key">Server</span>: Apache-Coyote/<span class="float">1.1</span>
Content-<span class="predefined-type">Type</span>: application/vnd.error+json;charset=ISO-<span class="integer">8859</span>-<span class="integer">1</span>

[
    {
        <span class="string"><span class="delimiter">&quot;</span><span class="content">logref</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">book.nullable,</span></span><span class="error">
</span>        <span class="string"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Property [title] of class [class rest.test.Book] cannot be null</span><span class="delimiter">&quot;</span></span>,
        <span class="string"><span class="delimiter">&quot;</span><span class="content">_links</span><span class="delimiter">&quot;</span></span>: {
            <span class="string"><span class="delimiter">&quot;</span><span class="content">resource</span><span class="delimiter">&quot;</span></span>: {
                <span class="string"><span class="delimiter">&quot;</span><span class="content">href</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://localhost:8080/rest-test/books</span><span class="delimiter">&quot;</span></span>
            }
        }
    }
]</code></pre>
</div>
</div>


<h2 id="binding">10.1.12 Customizing Binding of Resources</h2>

<div class='contribute-btn'>
    <button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/3.2.x/src/en/guide/webServices/REST/binding.adoc"'>
        <i class='fa fa-pencil-square-o'></i> Improve this doc
    </button>
</div>


<div class="paragraph">
<p>The framework provides a sophisticated but simple mechanism for binding REST requests to domain objects and command objects.  One way to take advantage of this is to bind the <code>request</code> property in a controller the <code>properties</code> of a domain class.  Given the following XML as the body of the request, the <code>createBook</code> action will create a new <code>Book</code> and assign "The Stand" to the <code>title</code> property and "Stephen King" to the <code>authorName</code> property.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">&lt;?xml version=<span class="string"><span class="delimiter">&quot;</span><span class="content">1.0</span><span class="delimiter">&quot;</span></span> encoding=<span class="string"><span class="delimiter">&quot;</span><span class="content">UTF-8</span><span class="delimiter">&quot;</span></span>?&gt;
&lt;book&gt;
    &lt;title&gt;The Stand&lt;<span class="regexp"><span class="delimiter">/</span><span class="content">title&gt;</span></span><span class="error">
</span>    &lt;authorName&gt;Stephen King&lt;<span class="regexp"><span class="delimiter">/</span><span class="content">authorName&gt;</span></span><span class="error">
</span>&lt;<span class="regexp"><span class="delimiter">/</span><span class="content">book&gt;</span></span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="type">class</span> <span class="class">BookController</span> {

    <span class="keyword">def</span> <span class="function">createBook</span>() {
        <span class="keyword">def</span> book = <span class="keyword">new</span> <span class="predefined-type">Book</span>()
        book.properties = request

        <span class="comment">// ...</span>
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Command objects will automatically be bound with the body of the request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="type">class</span> <span class="class">BookController</span> {
    <span class="keyword">def</span> <span class="function">createBook</span>(BookCommand book) {

        <span class="comment">// ...</span>
    }
}

<span class="type">class</span> <span class="class">BookCommand</span> {
    <span class="predefined-type">String</span> title
    <span class="predefined-type">String</span> authorName
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the command object type is a domain class and the root element of the XML document contains an <code>id</code> attribute, the <code>id</code> value will be used to retrieve the corresponding persistent instance from the database and then the rest of the document will be bound to the instance.  If no corresponding record is found in the database, the command object reference will be null.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">&lt;?xml version=<span class="string"><span class="delimiter">&quot;</span><span class="content">1.0</span><span class="delimiter">&quot;</span></span> encoding=<span class="string"><span class="delimiter">&quot;</span><span class="content">UTF-8</span><span class="delimiter">&quot;</span></span>?&gt;
&lt;book id=<span class="string"><span class="delimiter">&quot;</span><span class="content">42</span><span class="delimiter">&quot;</span></span>&gt;
    &lt;title&gt;Walden&lt;<span class="regexp"><span class="delimiter">/</span><span class="content">title&gt;</span></span><span class="error">
</span>    &lt;authorName&gt;Henry David Thoreau&lt;<span class="regexp"><span class="delimiter">/</span><span class="content">authorName&gt;</span></span><span class="error">
</span>&lt;<span class="regexp"><span class="delimiter">/</span><span class="content">book&gt;</span></span></code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="type">class</span> <span class="class">BookController</span> {
    <span class="keyword">def</span> <span class="function">updateBook</span>(<span class="predefined-type">Book</span> book) {
        <span class="comment">// The book will have been retrieved from the database and updated</span>
        <span class="comment">// by doing something like this:</span>
        <span class="comment">//</span>
        <span class="comment">// book == Book.get('42')</span>
        <span class="comment">// if(book != null) {</span>
        <span class="comment">//    book.properties = request</span>
        <span class="comment">// }</span>
        <span class="comment">//</span>
        <span class="comment">// the code above represents what the framework will</span>
        <span class="comment">// have done. There is no need to write that code.</span>

        <span class="comment">// ...</span>

    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The data binding depends on an instance of the <a href="http://docs.grails.org/3.2.11/api/grails/databinding/DataBindingSource.html">DataBindingSource</a> interface created by an instance of the <a href="http://docs.grails.org/3.2.11/api/org/grails/databinding/bindingsource/DataBindingSourceCreator.html">DataBindingSourceCreator</a> interface.  The specific implementation of <code>DataBindingSourceCreator</code> will be selected based on the <code>contentType</code> of the request.  Several implementations are provided to handle common content types.  The default implementations will be fine for most use cases.  The following table lists the content types which are supported by the core framework and which <code>DataBindingSourceCreator</code> implementations are used for each. All of the implementation classes are in the <code>org.grails.databinding.bindingsource</code> package.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Content Type(s)</th>
<th class="tableblock halign-left valign-top">Bean Name</th>
<th class="tableblock halign-left valign-top">DataBindingSourceCreator Impl.</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">application/xml, text/xml</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">xmlDataBindingSourceCreator</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">XmlDataBindingSourceCreator</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">application/json, text/json</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jsonDataBindingSourceCreator</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">JsonDataBindingSourceCreator</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">application/hal+json</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">halJsonDataBindingSourceCreator</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">HalJsonDataBindingSourceCreator</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">application/hal+xml</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">halXmlDataBindingSourceCreator</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">HalXmlDataBindingSourceCreator</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>In order to provide your own <code>DataBindingSourceCreator</code> for any of those content types, write a class which implements
<code>DataBindingSourceCreator</code> and register an instance of that class in the Spring application context.  If you
are replacing one of the existing helpers, use the corresponding bean name from above.  If you are providing a
helper for a content type other than those accounted for by the core framework, the bean name may be anything that
you like but you should take care not to conflict with one of the bean names above.</p>
</div>
<div class="paragraph">
<p>The <code>DataBindingSourceCreator</code> interface defines just 2 methods:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> org.grails.databinding.bindingsource

<span class="keyword">import</span> <span class="include">grails.web.mime.MimeType</span>
<span class="keyword">import</span> <span class="include">grails.databinding.DataBindingSource</span>

<span class="comment">/**
 * A factory for DataBindingSource instances
 *
 * @since 2.3
 * @see DataBindingSourceRegistry
 * @see DataBindingSource
 *
 */</span>
<span class="type">interface</span> DataBindingSourceCreator {

    <span class="comment">/**
     * `return All of the {`link MimeType} supported by this helper
     */</span>
    MimeType<span class="type">[]</span> getMimeTypes()

    <span class="comment">/**
     * Creates a DataBindingSource suitable for binding bindingSource to bindingTarget
     *
     * @param mimeType a mime type
     * @param bindingTarget the target of the data binding
     * @param bindingSource the value being bound
     * @return a DataBindingSource
     */</span>
    DataBindingSource createDataBindingSource(MimeType mimeType, <span class="predefined-type">Object</span> bindingTarget, <span class="predefined-type">Object</span> bindingSource)
}</code></pre>
</div>
</div>
<div class="paragraph">
<p><a href="http://docs.grails.org/3.2.11/api/org/grails/web/databinding/bindingsource/AbstractRequestBodyDataBindingSourceCreator.html">AbstractRequestBodyDataBindingSourceCreator</a>
is an abstract class designed to be extended to simplify writing custom <code>DataBindingSourceCreator</code> classes.  Classes which
extend <code>AbstractRequestbodyDatabindingSourceCreator</code> need to implement a method named <code>createBindingSource</code>
which accepts an <code>InputStream</code> as an argument and returns a <code>DataBindingSource</code> as well as implementing the <code>getMimeTypes</code>
method described in the <code>DataBindingSourceCreator</code> interface above.  The <code>InputStream</code> argument to <code>createBindingSource</code>
provides access to the body of the request.</p>
</div>
<div class="paragraph">
<p>The code below shows a simple implementation.</p>
</div>
<div class="listingblock">
<div class="title">src/main/groovy/com/demo/myapp/databinding/MyCustomDataBindingSourceCreator.groovy</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="keyword">package</span> com.demo.myapp.databinding

<span class="keyword">import</span> <span class="include">grails.web.mime.MimeType</span>
<span class="keyword">import</span> <span class="include">grails.databinding.DataBindingSource</span>
<span class="keyword">import</span> <span class="include">org</span>...<span class="include">databinding.SimpleMapDataBindingSource</span>
<span class="keyword">import</span> <span class="include">org</span>...<span class="include">databinding.bindingsource.AbstractRequestBodyDataBindingSourceCreator</span>

<span class="comment">/**
 * A custom DataBindingSourceCreator capable of parsing key value pairs out of
 * a request body containing a comma separated list of key:value pairs like:
 *
 * name:Herman,age:99,town:STL
 *
 */</span>
<span class="type">class</span> <span class="class">MyCustomDataBindingSourceCreator</span> <span class="directive">extends</span> AbstractRequestBodyDataBindingSourceCreator {

    <span class="annotation">@Override</span>
    <span class="directive">public</span> MimeType<span class="type">[]</span> getMimeTypes() {
        [<span class="keyword">new</span> MimeType(<span class="string"><span class="delimiter">'</span><span class="content">text/custom+demo+csv</span><span class="delimiter">'</span></span>)] <span class="keyword">as</span> MimeType<span class="type">[]</span>
    }

    <span class="annotation">@Override</span>
    <span class="directive">protected</span> DataBindingSource createBindingSource(<span class="predefined-type">InputStream</span> inputStream) {
        <span class="keyword">def</span> map = [:]

        <span class="keyword">def</span> reader = <span class="keyword">new</span> <span class="predefined-type">InputStreamReader</span>(inputStream)

        <span class="comment">// this is an obviously naive parser and is intended</span>
        <span class="comment">// for demonstration purposes only.</span>

        reader.eachLine { line -&gt;
            <span class="keyword">def</span> keyValuePairs = line.split(<span class="string"><span class="delimiter">'</span><span class="content">,</span><span class="delimiter">'</span></span>)
            keyValuePairs.each { keyValuePair -&gt;
                <span class="keyword">if</span>(keyValuePair?.trim()) {
                    <span class="keyword">def</span> keyValuePieces = keyValuePair.split(<span class="string"><span class="delimiter">'</span><span class="content">:</span><span class="delimiter">'</span></span>)
                    <span class="keyword">def</span> key = keyValuePieces[<span class="integer">0</span>].trim()
                    <span class="keyword">def</span> value = keyValuePieces[<span class="integer">1</span>].trim()
                    map&lt;&lt;key&gt;&gt; = value
                }
            }
        }

        <span class="comment">// create and return a DataBindingSource which contains the parsed data</span>
        <span class="keyword">new</span> SimpleMapDataBindingSource(map)
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>An instance of <code>MyCustomDataSourceCreator</code> needs to be registered in the spring application context.</p>
</div>
<div class="listingblock">
<div class="title">grails-app/conf/spring/resources.groovy</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">beans = {

    myCustomCreator com.demo.myapp.databinding.MyCustomDataBindingSourceCreator

    <span class="comment">// ...</span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>With that in place the framework will use the <code>myCustomCreator</code> bean any time a <code>DataBindingSourceCreator</code> is needed
to deal with a request which has a <code>contentType</code> of "text/custom+demo+csv".</p>
</div>


                <div style="clear:both;margin-top:15px;"></div>
                
                    <div class="toc-item prev-left"><a href="../../guide/traits.html">&lt;&lt; <strong>9</strong><span>Traits</span></a></div>
                
                    <div class="toc-item next-right"><a href="../../guide/async.html"><strong>11</strong><span>Asynchronous Programming</span> >></a></div>
                
                <div style="clear:both"></div>
            </div>
        </td>
        <td id="col2">
            <div class="local clearfix">
                <div class="local-title">
                    <a href="../../guide/index.html" target="mainFrame">Quick Reference</a>
                    <span class="toggle">(<a href="#" onclick="localToggle(); return false;">hide</a>)</span>
                </div>
                <div class="menu">
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Command Line</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../../ref/Command%20Line/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/bug-report.html">bug-report</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/clean.html">clean</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/compile.html">compile</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/console.html">console</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-app.html">create-app</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-command.html">create-command</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-controller.html">create-controller</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-domain-class.html">create-domain-class</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-functional-test.html">create-functional-test</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-hibernate-cfg-xml.html">create-hibernate-cfg-xml</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-integration-test.html">create-integration-test</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-interceptor.html">create-interceptor</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-plugin.html">create-plugin</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-profile.html">create-profile</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-script.html">create-script</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-service.html">create-service</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-taglib.html">create-taglib</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/create-unit-test.html">create-unit-test</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/dependency-report.html">dependency-report</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/docs.html">docs</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/generate-all.html">generate-all</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/generate-controller.html">generate-controller</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/generate-views.html">generate-views</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/help.html">help</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/install-templates.html">install-templates</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/list-plugins.html">list-plugins</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/list-profiles.html">list-profiles</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/package-plugin.html">package-plugin</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/package.html">package</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/plugin-info.html">plugin-info</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/profile-info.html">profile-info</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/run-app.html">run-app</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/run-command.html">run-command</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/run-script.html">run-script</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/schema-export.html">schema-export</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/shell.html">shell</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/stats.html">stats</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/stop-app.html">stop-app</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/test-app.html">test-app</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Command%20Line/war.html">war</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Constraints</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../../ref/Constraints/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../../ref/Constraints/attributes.html">attributes</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/bindable.html">bindable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/blank.html">blank</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/creditCard.html">creditCard</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/email.html">email</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/inList.html">inList</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/matches.html">matches</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/max.html">max</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/maxSize.html">maxSize</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/min.html">min</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/minSize.html">minSize</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/notEqual.html">notEqual</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/nullable.html">nullable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/range.html">range</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/scale.html">scale</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/size.html">size</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/unique.html">unique</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/url.html">url</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/validator.html">validator</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Constraints/widget.html">widget</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Controllers</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../../ref/Controllers/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../../ref/Controllers/actionName.html">actionName</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/allowedMethods.html">allowedMethods</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/bindData.html">bindData</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/chain.html">chain</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/controllerName.html">controllerName</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/defaultAction.html">defaultAction</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/errors.html">errors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/flash.html">flash</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/forward.html">forward</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/grailsApplication.html">grailsApplication</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/hasErrors.html">hasErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/namespace.html">namespace</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/params.html">params</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/redirect.html">redirect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/render.html">render</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/request.html">request</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/respond.html">respond</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/response.html">response</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/responseFormats.html">responseFormats</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/scope.html">scope</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/servletContext.html">servletContext</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/session.html">session</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/withForm.html">withForm</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Controllers/withFormat.html">withFormat</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Database Mapping</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/autoImport.html">autoImport</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/autoTimestamp.html">autoTimestamp</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/batchSize.html">batchSize</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/cache.html">cache</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/cascade.html">cascade</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/column.html">column</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/comment.html">comment</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/discriminator.html">discriminator</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/dynamicInsert.html">dynamicInsert</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/dynamicUpdate.html">dynamicUpdate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/fetch.html">fetch</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/id.html">id</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/ignoreNotFound.html">ignoreNotFound</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/indexColumn.html">indexColumn</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/insertable.html">insertable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/joinTable.html">joinTable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/lazy.html">lazy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/order.html">order</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/sort.html">sort</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/table.html">table</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/type.html">type</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/updateable.html">updateable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Database%20Mapping/version.html">version</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Domain Classes</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/addTo.html">addTo</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/attach.html">attach</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/belongsTo.html">belongsTo</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/clearErrors.html">clearErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/constraints.html">constraints</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/count.html">count</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/countBy.html">countBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/createCriteria.html">createCriteria</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/delete.html">delete</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/discard.html">discard</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/embedded.html">embedded</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/errors.html">errors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/executeQuery.html">executeQuery</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/executeUpdate.html">executeUpdate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/exists.html">exists</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/fetchMode.html">fetchMode</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/find.html">find</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/findAll.html">findAll</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/findAllBy.html">findAllBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/findAllWhere.html">findAllWhere</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/findBy.html">findBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/findOrCreateBy.html">findOrCreateBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/findOrCreateWhere.html">findOrCreateWhere</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/findOrSaveBy.html">findOrSaveBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/findOrSaveWhere.html">findOrSaveWhere</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/findWhere.html">findWhere</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/first.html">first</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/get.html">get</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/getAll.html">getAll</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/getDirtyPropertyNames.html">getDirtyPropertyNames</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/getPersistentValue.html">getPersistentValue</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/hasErrors.html">hasErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/hasMany.html">hasMany</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/hasOne.html">hasOne</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/ident.html">ident</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/instanceOf.html">instanceOf</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/isAttached.html">isAttached</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/isDirty.html">isDirty</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/last.html">last</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/list.html">list</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/listOrderBy.html">listOrderBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/load.html">load</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/lock.html">lock</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/mapWith.html">mapWith</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/mappedBy.html">mappedBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/mapping.html">mapping</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/merge.html">merge</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/namedQueries.html">namedQueries</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/properties.html">properties</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/read.html">read</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/refresh.html">refresh</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/removeFrom.html">removeFrom</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/save.html">save</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/transients.html">transients</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/validate.html">validate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/where.html">where</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/whereAny.html">whereAny</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/withCriteria.html">withCriteria</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/withNewSession.html">withNewSession</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/withSession.html">withSession</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Domain%20Classes/withTransaction.html">withTransaction</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Plug-ins</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../../ref/Plug-ins/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../../ref/Plug-ins/URL%20mappings.html">URL mappings</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Plug-ins/codecs.html">codecs</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Plug-ins/controllers.html">controllers</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Plug-ins/core.html">core</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Plug-ins/dataSource.html">dataSource</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Plug-ins/domainClasses.html">domainClasses</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Plug-ins/hibernate.html">hibernate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Plug-ins/i18n.html">i18n</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Plug-ins/logging.html">logging</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Plug-ins/scaffolding.html">scaffolding</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Plug-ins/services.html">services</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Plug-ins/servlets.html">servlets</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Services</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../../ref/Services/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../../ref/Services/scope.html">scope</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Services/transactional.html">transactional</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Servlet API</h1><div class="menu-sub">
                        
                            
                            <div class="menu-item"><a href="../../ref/Servlet%20API/request.html">request</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Servlet%20API/response.html">response</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Servlet%20API/servletContext.html">servletContext</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Servlet%20API/session.html">session</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Tag Libraries</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../../ref/Tag%20Libraries/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../../ref/Tag%20Libraries/actionName.html">actionName</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tag%20Libraries/controllerName.html">controllerName</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tag%20Libraries/flash.html">flash</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tag%20Libraries/pageScope.html">pageScope</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tag%20Libraries/params.html">params</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tag%20Libraries/request.html">request</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tag%20Libraries/response.html">response</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tag%20Libraries/servletContext.html">servletContext</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tag%20Libraries/session.html">session</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Tags</h1><div class="menu-sub">
                        
                            
                            <div class="menu-item"><a href="../../ref/Tags/actionSubmit.html">actionSubmit</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/actionSubmitImage.html">actionSubmitImage</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/applyLayout.html">applyLayout</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/checkBox.html">checkBox</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/collect.html">collect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/cookie.html">cookie</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/country.html">country</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/countrySelect.html">countrySelect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/createLink.html">createLink</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/createLinkTo.html">createLinkTo</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/currencySelect.html">currencySelect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/datePicker.html">datePicker</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/each.html">each</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/eachError.html">eachError</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/else.html">else</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/elseif.html">elseif</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/external.html">external</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/field.html">field</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/fieldError.html">fieldError</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/fieldValue.html">fieldValue</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/findAll.html">findAll</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/form.html">form</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/formatBoolean.html">formatBoolean</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/formatDate.html">formatDate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/formatNumber.html">formatNumber</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/grep.html">grep</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/hasErrors.html">hasErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/header.html">header</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/hiddenField.html">hiddenField</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/if.html">if</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/img.html">img</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/include.html">include</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/isAvailable.html">isAvailable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/isNotAvailable.html">isNotAvailable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/javascript.html">javascript</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/join.html">join</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/layoutBody.html">layoutBody</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/layoutHead.html">layoutHead</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/layoutTitle.html">layoutTitle</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/link.html">link</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/localeSelect.html">localeSelect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/message.html">message</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/meta.html">meta</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/pageProperty.html">pageProperty</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/paginate.html">paginate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/passwordField.html">passwordField</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/radio.html">radio</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/radioGroup.html">radioGroup</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/render.html">render</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/renderErrors.html">renderErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/resource.html">resource</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/select.html">select</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/set.html">set</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/sortableColumn.html">sortableColumn</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/submitButton.html">submitButton</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/textArea.html">textArea</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/textField.html">textField</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/timeZoneSelect.html">timeZoneSelect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/unless.html">unless</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/uploadForm.html">uploadForm</a>
                            </div>
                            
                            <div class="menu-item"><a href="../../ref/Tags/while.html">while</a>
                            </div>
                            
                            </div>
                    </div>
                    
                </div>
            </div>
        </td>
    </tr>
</table>

<div id="footer">
    Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
    
</div>

<script type="text/javascript" src="../js/docs.js"></script>

</body>
</html>
